Skip to main content
defineBlokkli() is a compiler macro and composable auto-imported by the blökkli Nuxt module. Call it inside <script lang="ts" setup> in every block component to register the component as a blökkli block and declare its options. At build time, blökkli reads your defineBlokkli() calls to generate typed option resolvers, chunk manifests, and editor metadata.

​
Signature

function defineBlokkli(options: BlokkliOptions): { options: ComputedRef<ResolvedOptions> }

​
Parameters

​
bundle
string
required
The unique bundle identifier for this block type. Must exactly match the bundle string in your block data (e.g. the paragraph machine name in Drupal, or the type field from your API).Examples: 'text', 'hero', 'image-gallery'
​
options
object
Local option definitions for this block. Each key is an option name; each value is an option definition object. Options are rendered as controls in the blökkli editor sidebar. The resolved values are returned as a reactive ComputedRef by defineBlokkli().See Block Options for all available option types (radios, checkbox, range, select, text, and more) and their full configuration properties.
​
globalOptions
string[]
An array of global option keys to include on this block. Global options are defined once in nuxt.config.ts under blokkli.globalOptions and reused across all blocks that opt in — useful for shared concerns like color scheme or spacing scale.
// nuxt.config.ts
blokkli: {
  globalOptions: {
    colorScheme: {
      type: 'radios',
      label: 'Color scheme',
      default: 'light',
      options: { light: 'Light', dark: 'Dark' },
    },
  },
}

// In a block component
defineBlokkli({
  bundle: 'hero',
  globalOptions: ['colorScheme'],
})
​
editor
object
Override editor behaviors for this specific block. All properties are optional.
​
chunkName
string
Named async chunk for code splitting. Blocks that share the same chunkName are bundled into a single lazy-loaded chunk. Group blocks that are typically used together (e.g. all form-related blocks) to reduce the number of network requests on first load.
​
renderFor
object[]
A constraint array that limits where this block is rendered. Each entry is an object specifying conditions such as entity type or bundle. Blocks are only rendered when their constraints match the current context; non-matching blocks are skipped during render.

​
Return Value

defineBlokkli() returns an object with a single property:
​
options
ComputedRef<ResolvedOptions>
Reactive resolved option values. Updates automatically when the user changes options in the editor. Access individual values as options.value.myOptionKey in <script setup>, or as options.myKey directly in templates — Vue unwraps ComputedRef automatically in template expressions.
const { options } = defineBlokkli({ bundle: 'card', options: { /* ... */ } })

// In <script setup>: access via options.value.myKey
// In <template>:     access via options.myKey  (Vue auto-unwraps)

​
Full Example

The following component demonstrates a card block with three local options and one global option: 
<template>
  <article
    :class="['card', `card--${options.variant}`]"
    :style="{ '--gap': `${options.gap}px` }"
  >
    <img v-if="options.showImage && image" :src="image" alt="" />
    <h2>{{ title }}</h2>
    <p>{{ body }}</p>
  </article>
</template>

<script lang="ts" setup>
defineProps<{
  title: string
  body: string
  image?: string
}>()

const { options } = defineBlokkli({
  bundle: 'card',
  globalOptions: ['colorScheme'],
  options: {
    variant: {
      type: 'radios',
      label: 'Card variant',
      default: 'default',
      options: { default: 'Default', featured: 'Featured', compact: 'Compact' },
    },
    showImage: {
      type: 'checkbox',
      label: 'Show image',
      default: true,
    },
    gap: {
      type: 'range',
      label: 'Inner gap',
      default: 16,
      min: 0,
      max: 48,
    },
  },
})
</script>
In the editor, blökkli automatically renders a Radios control for variant, a Checkbox for showImage, and a Range slider for gap in the options sidebar — with no additional configuration required.