> ## 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.

# useBlokkli() — Editor State, Events and Utilities

> API reference for the useBlokkli() composable. Access editor state, event bus, and utilities from within custom block or feature components.

`useBlokkli()` is a composable that provides access to the editor's state, event system, and utilities from within block components and custom editor features. It is auto-imported by the blökkli Nuxt module — no explicit import is needed.

## Availability

<Note>
  `useBlokkli()` must be called from a component that is a descendant of
  `<BlokkliProvider>`. Calling it outside of that context results in a runtime
  warning and returns a no-op stub.
</Note>

* **Custom feature components** — the primary use case. Features defined with `defineBlokkliFeature()` can use `useBlokkli()` to react to editor state and subscribe to events.
* **Block components** — use `useBlokkli()` inside any block component to apply editor-specific styles, hide controls, or respond to selection events.
* **Nested components** — any component rendered inside a `<BlokkliProvider>` tree can call `useBlokkli()`, regardless of depth.

## Signature

```typescript theme={null}
function useBlokkli(): BlokkliContext
```

## Return Value

<ResponseField name="state" type="Ref<EditorState>">
  A reactive ref containing the current editor state. The ref updates whenever
  the editor state changes — use it with `computed()` or `watchEffect()` to
  derive reactive values.

  <Expandable title="EditorState properties">
    <ResponseField name="state.value.isEditing" type="boolean">
      `true` while the editor overlay is active. Use this to conditionally show
      or hide editor-only UI in your block components.
    </ResponseField>

    <ResponseField name="state.value.currentEntityUuid" type="string">
      The UUID of the entity currently open in the editor. Matches the
      `entity_uuid` passed to `<BlokkliProvider>`.
    </ResponseField>

    <ResponseField name="state.value.blocks" type="BlockData[]">
      The current list of block data objects loaded into the editor. Each entry
      contains at minimum `uuid`, `bundle`, and `hostField`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="eventBus" type="EventBus">
  The editor's shared event bus. Subscribe to built-in editor events (block
  selection, drag interactions, state changes) or emit custom events to
  communicate between features.
</ResponseField>

<ResponseField name="$t" type="(key: string) => string">
  Translation helper for editor UI strings. Resolves the given key against the
  active editor locale. Use this inside custom feature components to keep UI
  strings translatable alongside the rest of the editor.
</ResponseField>

## Example: Reading Editor State in a Block

Apply a CSS class conditionally based on whether the editor is active:

```vue theme={null}
<template>
  <div :class="{ 'is-editing': isEditing }">
    <slot />
  </div>
</template>

<script lang="ts" setup>
const { state } = useBlokkli()
const isEditing = computed(() => state.value.isEditing)
</script>
```

## Example: Subscribing to Events in a Feature

Listen for block selection changes inside a custom editor feature. Store the handler reference so it can be removed on unmount:

```typescript theme={null}
const { eventBus } = useBlokkli()

const onSelectBlocks = (uuids: string[]) => {
  console.log('Selected blocks:', uuids)
}

onMounted(() => {
  eventBus.on('select:blocks', onSelectBlocks)
})

onUnmounted(() => {
  eventBus.off('select:blocks', onSelectBlocks)
})
```

<Warning>
  Always clean up event subscriptions when the component unmounts. Pass the
  same handler reference to `eventBus.off()` that you passed to
  `eventBus.on()` — inline arrow functions create a new reference each time
  and cannot be removed.
</Warning>

## Example: Using the Translation Helper

```vue theme={null}
<template>
  <button>{{ $t('blokkli.feature.publish.label') }}</button>
</template>

<script lang="ts" setup>
const { $t } = useBlokkli()
</script>
```

<Note>
  The full list of event names and their payload types is available in the
  TypeScript types exported from `@blokkli/editor`. Your IDE will provide
  autocomplete for all `eventBus.on(eventName, handler)` calls when your
  project has the package installed.
</Note>