Skip to main content
These optional adapter methods unlock blökkli’s advanced features. Implement the ones relevant to your project — blökkli automatically activates the corresponding editor feature when the method is present in your adapter.
All methods described on this page are fully typed. Check the TypeScript types exported from @blokkli/editor for the exact parameter shapes and return types, and use them in your adapter for end-to-end type safety.

​
Library (Reusable Blocks)

The library feature lets editors save blocks as reusable items and insert them across multiple pages. All four methods below work together — implement them as a group to enable the full library workflow.
Returns the list of saved reusable block items available to the current user. blökkli calls this when the user opens the Library panel.Signature
async getLibraryItems(): Promise<LibraryItem[]>
Example
async getLibraryItems() {
  return $fetch('/api/library')
}
Saves an existing block to the library under a user-supplied title. Called when the user selects “Save to library” from the block context menu.Signature
async makeBlockReusable({
  uuid,
  title,
}: {
  uuid: string
  title: string
}): Promise<void>
​
uuid
string
required
UUID of the block to save as a reusable item.
​
title
string
required
The display label for the library item, as entered by the user.
Example
async makeBlockReusable({ uuid, title }) {
  await $fetch('/api/library', {
    method: 'POST',
    body: { uuid, title },
  })
}
Inserts a library item at the current drop position. Called when the user drags a library item onto the canvas or clicks to insert it.Signature
async addLibraryItem({
  uuid,
  hostField,
  preceedingUuid,
}: {
  uuid: string
  hostField: string
  preceedingUuid: string | null
}): Promise<void>
​
uuid
string
required
UUID of the library item to insert.
​
hostField
string
required
The target field name.
​
preceedingUuid
string | null
required
UUID of the block that the library item should be placed after. null inserts at the start of the field.
Example
async addLibraryItem({ uuid, hostField, preceedingUuid }) {
  await $fetch('/api/library/insert', {
    method: 'POST',
    body: { uuid, hostField, preceedingUuid },
  })
}
Converts a library reference back into a standalone block. Called when the user selects “Detach from library” on a reusable block instance.Signature
async detachReusableBlock({ uuid }: { uuid: string }): Promise<void>
​
uuid
string
required
UUID of the library reference block to detach.
Example
async detachReusableBlock({ uuid }) {
  await $fetch(`/api/library/${uuid}/detach`, { method: 'POST' })
}

​
Media Library

The media library panel lets editors search for existing media assets and insert blocks from them directly.
Returns paginated media search results for the media library panel. Called whenever the user types into the search field or navigates to a new page of results.Signature
async mediaLibraryGetResults({
  searchText,
  page,
}: {
  searchText: string
  page: number
}): Promise<MediaLibraryResults>
​
searchText
string
required
The current search query string. May be an empty string when the user has not typed anything.
​
page
number
required
Zero-based page index for pagination.
Example
async mediaLibraryGetResults({ searchText, page }) {
  return $fetch('/api/media', {
    query: { q: searchText, page },
  })
}
Adds a block from a selected media item. Called when the user clicks a media result in the library panel.Signature
async mediaLibraryAddBlock({
  mediaId,
  hostField,
  preceedingUuid,
}: {
  mediaId: string
  hostField: string
  preceedingUuid: string | null
}): Promise<void>
​
mediaId
string
required
The identifier of the selected media asset.
​
hostField
string
required
The target field name.
​
preceedingUuid
string | null
required
UUID of the preceding block. null inserts at the start of the field.
Example
async mediaLibraryAddBlock({ mediaId, hostField, preceedingUuid }) {
  await $fetch('/api/blocks/from-media', {
    method: 'POST',
    body: { mediaId, hostField, preceedingUuid },
  })
}

​
AI Assistant

The AI assistant panel lets editors generate block content from a natural language prompt.
Called when the user submits a prompt in the AI assistant panel. Return an array of suggested block definitions that the editor can present as insertion candidates.Signature
async assistantGetResults({
  prompt,
}: {
  prompt: string
}): Promise<AssistantResult[]>
​
prompt
string
required
The natural language prompt entered by the user.
Example
async assistantGetResults({ prompt }) {
  return $fetch('/api/ai/suggest', {
    method: 'POST',
    body: { prompt },
  })
}
Inserts a block from an AI suggestion. Called when the user selects one of the results returned by assistantGetResults().Signature
async assistantAddBlockFromResult({
  result,
  hostField,
  preceedingUuid,
}: {
  result: AssistantResult
  hostField: string
  preceedingUuid: string | null
}): Promise<void>
​
result
AssistantResult
required
The full result object as returned by assistantGetResults().
​
hostField
string
required
The target field name.
​
preceedingUuid
string | null
required
UUID of the preceding block. null inserts at the start of the field.
Example
async assistantAddBlockFromResult({ result, hostField, preceedingUuid }) {
  await $fetch('/api/blocks/from-ai', {
    method: 'POST',
    body: { result, hostField, preceedingUuid },
  })
}

​
Comments

The comments feature allows editors to annotate blocks with discussion threads.
Adds a comment to a specific block. Called when the user submits a comment from the block’s comment input.Signature
async addComment({
  uuid,
  body,
}: {
  uuid: string
  body: string
}): Promise<void>
​
uuid
string
required
UUID of the block being commented on.
​
body
string
required
The comment text.
Example
async addComment({ uuid, body }) {
  await $fetch('/api/comments', {
    method: 'POST',
    body: { uuid, body },
  })
}
Loads all comments for the current entity. blökkli calls this on editor activation and after each comment mutation.Signature
async loadComments(): Promise<Comment[]>
Example
async loadComments() {
  return $fetch(
    `/api/content/${ctx.state.value.currentEntityUuid}/comments`
  )
}
Marks a comment as resolved. Called when the user clicks the resolve button on a comment thread.Signature
async resolveComment({ commentUuid }: { commentUuid: string }): Promise<void>
​
commentUuid
string
required
UUID of the comment to resolve.
Example
async resolveComment({ commentUuid }) {
  await $fetch(`/api/comments/${commentUuid}/resolve`, { method: 'POST' })
}

​
Content Search

The content search panel lets editors find existing content items and insert blocks from them.
Returns tab definitions for the content search panel. Each tab represents a separate searchable content source (for example, “Articles”, “Products”).Signature
async getContentSearchTabs(): Promise<ContentSearchTab[]>
Example
async getContentSearchTabs() {
  return [
    { id: 'articles', label: 'Articles' },
    { id: 'products', label: 'Products' },
  ]
}
Returns paginated search results for the active tab and query. Called whenever the user types or changes tabs.Signature
async getContentSearchResults({
  tab,
  query,
  page,
}: {
  tab: string
  query: string
  page: number
}): Promise<ContentSearchResults>
​
tab
string
required
The id of the active search tab.
​
query
string
required
The current search string.
​
page
number
required
Zero-based page index.
Example
async getContentSearchResults({ tab, query, page }) {
  return $fetch('/api/search', {
    query: { type: tab, q: query, page },
  })
}
Inserts a block from a search result. Called when the user clicks a result in the content search panel.Signature
async addContentSearchItem({
  item,
  hostField,
  preceedingUuid,
}: {
  item: ContentSearchItem
  hostField: string
  preceedingUuid: string | null
}): Promise<void>
​
item
ContentSearchItem
required
The full result object as returned by getContentSearchResults().
​
hostField
string
required
The target field name.
​
preceedingUuid
string | null
required
UUID of the preceding block. null inserts at the start of the field.
Example
async addContentSearchItem({ item, hostField, preceedingUuid }) {
  await $fetch('/api/blocks/from-search', {
    method: 'POST',
    body: { item, hostField, preceedingUuid },
  })
}

​
Import

The import feature lets editors pull blocks from other entities into the current one.
Returns available blocks to import from other entities of the given type and bundle. Displayed in the Import panel.Signature
async getImportItems({
  entityType,
  entityBundle,
}: {
  entityType: string
  entityBundle: string
}): Promise<ImportItem[]>
​
entityType
string
required
The entity type to search for importable blocks (e.g., 'node').
​
entityBundle
string
required
The entity bundle to search (e.g., 'page', 'article').
Example
async getImportItems({ entityType, entityBundle }) {
  return $fetch('/api/blocks/importable', {
    query: { entityType, entityBundle },
  })
}
Imports the selected blocks from another entity into the current one. Called when the user confirms an import selection.Signature
async importFromExisting({
  uuids,
  hostField,
  preceedingUuid,
}: {
  uuids: string[]
  hostField: string
  preceedingUuid: string | null
}): Promise<void>
​
uuids
string[]
required
UUIDs of the blocks to import.
​
hostField
string
required
The target field name in the current entity.
​
preceedingUuid
string | null
required
UUID of the block to insert after. null inserts at the start of the field.
Example
async importFromExisting({ uuids, hostField, preceedingUuid }) {
  await $fetch('/api/blocks/import', {
    method: 'POST',
    body: { uuids, hostField, preceedingUuid },
  })
}

​
Preview

Builds the URL for the block edit form iframe. When implemented, blökkli renders this URL in an iframe panel when the user opens the edit form for a block — useful for embedding your existing backend edit forms.Signature
async buildEditableFrameUrl({ uuid }: { uuid: string }): Promise<string>
​
uuid
string
required
UUID of the block to build the edit URL for.
Example
async buildEditableFrameUrl({ uuid }) {
  return `/admin/blocks/${uuid}/edit?mode=iframe`
}
Generates a shareable preview URL for the current draft state — accessible without logging in. Useful for sharing a draft with stakeholders.Signature
async getPreviewGrantUrl({ uuid }: { uuid: string }): Promise<string>
​
uuid
string
required
UUID of the entity to generate a preview grant for.
Example
async getPreviewGrantUrl({ uuid }) {
  const data = await $fetch(`/api/preview-grant`, {
    method: 'POST',
    body: { uuid },
  })
  return data.url
}
The URL returned by getPreviewGrantUrl() is copied to the clipboard when the user clicks the Share Preview button in the toolbar. Ensure the URL is publicly accessible and includes a time-limited token to prevent permanent unauthorised access.