> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockli.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Defining and Using Global Block Options in blökkli

> Define reusable block options once in nuxt.config.ts and share them across all blökkli block types. Covers all seven option types and opt-in usage.

Global options are reusable option definitions you configure **once** in `nuxt.config.ts` and
then reference from any block by listing the option key in the `globalOptions` array inside
`defineBlokkli()`. Instead of duplicating a `spacing` or `colorScheme` option across every block
component, you define it centrally and let each block opt in.

***

## Defining Global Options

Add your shared option definitions under the `globalOptions` key in the `blokkli` module config:

```typescript theme={null}
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@blokkli/editor'],
  blokkli: {
    itemEntityType: 'block',
    globalOptions: {
      spacing: {
        type: 'radios',
        label: 'Spacing',
        default: 'normal',
        options: {
          compact: 'Compact',
          normal: 'Normal',
          wide: 'Wide',
        },
      },
      colorScheme: {
        type: 'radios',
        label: 'Color Scheme',
        default: 'light',
        options: {
          light: 'Light',
          dark: 'Dark',
        },
      },
    },
  },
})
```

Each key you define here becomes a named option that any block can reference. The value object
uses the same shape as block-level options — the same `type`, `label`, `default`, and
type-specific properties all apply.

***

## Using Global Options in a Block

Inside a block component, pass the keys you want to opt in to as an array to `globalOptions`:

```typescript theme={null}
const { options } = defineBlokkli({
  bundle: 'hero',
  globalOptions: ['spacing', 'colorScheme'],
})

// options.spacing and options.colorScheme are now fully typed and reactive
```

blökkli merges global options into the block's options panel automatically. Editors see them
alongside any block-level options you define, and you consume them through the same `options`
object returned by `defineBlokkli()`.

***

## Available Option Types

Every option — whether global or block-level — uses one of the following types:

| Type         | Editor widget          | Value type           | Example use                      |
| ------------ | ---------------------- | -------------------- | -------------------------------- |
| `text`       | Single-line text input | `string`             | Short label, call-to-action text |
| `checkbox`   | Toggle checkbox        | `boolean`            | Show or hide an element          |
| `checkboxes` | Multi-select dropdown  | `string[]`           | Enable a set of features         |
| `radios`     | Radio button group     | `string`             | Select a layout variant          |
| `color`      | Color picker           | `string` (`#rrggbb`) | Background or text color         |
| `range`      | Range slider           | `number`             | Padding or spacing amount        |
| `number`     | Numeric input          | `number`             | Column count, font size          |

### `radios` Display Variants

The `radios` type supports an optional `displayAs` property that changes how the choices are
rendered in the editor panel:

<ParamField path="displayAs" type="string">
  Controls the visual presentation of a `radios` option in the editor UI.

  | Value      | Appearance                                               |
  | ---------- | -------------------------------------------------------- |
  | `'radios'` | Standard radio buttons (default)                         |
  | `'grid'`   | Visual grid layout — useful for layout or column options |
  | `'colors'` | Color swatch grid — pairs well with colour-value keys    |
  | `'icons'`  | Icon buttons — ideal for alignment or direction choices  |

  ```typescript theme={null}
  layout: {
    type: 'radios',
    label: 'Layout',
    default: 'single',
    displayAs: 'grid',
    options: {
      single: 'Single column',
      two: 'Two columns',
      three: 'Three columns',
    },
  }
  ```
</ParamField>

***

## Grouping Options

When a block exposes several options, you can group related ones together in the editor panel
by adding a `group` property to each option definition. blökkli collects options that share the
same group name into a labelled section, keeping the panel tidy for editors.

```typescript theme={null}
const { options } = defineBlokkli({
  bundle: 'hero',
  options: {
    heading: {
      type: 'text',
      label: 'Heading',
      group: 'Content',
      default: '',
    },
    backgroundColor: {
      type: 'color',
      label: 'Background',
      group: 'Appearance',
      default: '#ffffff',
    },
    padding: {
      type: 'range',
      label: 'Padding',
      group: 'Appearance',
      default: 2,
      min: 0,
      max: 10,
    },
  },
})
```

In this example the editor panel for the `hero` block shows two sections — **Content** (with the
heading field) and **Appearance** (with background colour and padding) — rather than a flat
unsorted list. You can use `group` on both block-level options and on global options that a block
has opted in to.