FrameworkJavaScript

BlockAPI: work with a single block

Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().

Edit this page on GitHub

Reaching the editor instance

The methods below run on the editor you created with new Blok(). They are available once editor.isReady resolves.

TypeScript

// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Methods

block.save()

Promise<void|SavedData>

Save the block content and return its data.

When to use

Returns just this block's data — handy for inspecting or persisting one block without editor.save()'s full walk.

TypeScript

const block = editor.blocks.getById('block-123');
const saved = await block.save();
// saved resolves to a SavedData object (or undefined if extraction fails):
// { id: 'block-123', tool: 'paragraph', data: { text: 'Block content' }, time: 1717000000000 }
console.log(saved?.data); // { text: 'Block content' }

block.validate(data)

Promise<boolean>

Validate block data against the tool's validation rules.

When to use

Runs the tool's validate() against given data; use it to reject empty or malformed blocks before saving.

TypeScript

const block = editor.blocks.getById('block-123');
const isValid = await block.validate({ text: 'Hello' });
if (!isValid) {
  console.log('Block data is invalid');
}

block.call(methodName, param?)

void

Call a custom method on the block's tool.

When to use

Escape hatch to invoke a custom method your tool exposes — for behaviour outside the standard BlockTool API.

TypeScript

const block = editor.blocks.getById('block-123');
// Call a custom method defined in the tool
block.call('showNotification', { message: 'Hello' });

block.dispatchChange()

void

Manually trigger the onChange callback for this block.

When to use

Call when you mutate a block outside Blok's knowledge (e.g. an async update) so change events and CRDT sync fire.

TypeScript

const block = editor.blocks.getById('block-123');
// Trigger change after invisible modification
block.dispatchChange();

block.getActiveToolboxEntry()

Promise<ToolboxConfigEntry | undefined>

Get the active toolbox entry for this block (e.g., Heading 1 vs Heading 2).

When to use

Resolves which toolbox variant is active (e.g. Heading 1 vs 2) — useful for reflecting state in custom UI.

TypeScript

const block = editor.blocks.getById('block-123');
const entry = await block.getActiveToolboxEntry();
if (entry) {
  console.log('Active entry:', entry.title);
}

Properties

Property	Type	Description
`id`	`string`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`name`	`string`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`config`	`ToolConfig`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`holder`	`HTMLElement`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`isEmpty`	`boolean`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`selected`	`boolean`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`focusable`	`boolean`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`stretched`	`boolean`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`parentId`	`string \| null`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`preservedData`	`BlockToolData`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().
`preservedTunes`	`{ [name: string]: BlockTuneData }`	Interface for working with individual blocks. Returned by blocks.getById(), blocks.getBlockByIndex(), and blocks.insert().