useBlocks(): read and mutate blocks from React

The block with the given id as a snapshot node, or null when unknown.

const node = blocks.getById('x9k2f1');
// → { id: 'x9k2f1', type: 'paragraph', parentId: null, contentIds: [] }

The direct children of a parent block, in document order. Pass null for the root blocks.

const rootBlocks = blocks.getChildren(null);
const rowBlocks = blocks.getChildren(databaseBlockId);

Insert one block (type, data, parentId, position, tunes, id, focus/caret, replace). `replace: true` combined with a `position` that targets an existing block replaces that block instead of inserting beside it — a programmatic "turn into". Returns the created node, or null when rejected (unknown tool type, dangling parentId, or a `replace` whose target is missing). An explicit id that already exists is insert-if-absent. Atomic — one undo step.

const node = blocks.insert({
  type: 'header',
  data: { text: 'New section', level: 2 },
  position: 'end',
  focus: true,
});
// → node.id is the new block's id (or null if rejected)

Insert several blocks atomically, in array order, as ONE undo step. Specs that fail are dropped; returns the successfully created nodes.

const nodes = blocks.insertMany([
  { type: 'header', data: { text: 'Title' } },
  { type: 'paragraph', data: { text: 'Body' } },
]);

Insert a pre-built NESTED subtree in one atomic operation. Children are inserted under their enclosing node recursively; placement options apply to the root only. Returns the root node, or null on a rejected/colliding id.

const root = blocks.insertTree({
  type: 'toggle',
  data: { text: 'Details' },
  children: [
    { type: 'paragraph', data: { text: 'Hidden content' } },
  ],
});

Convert a Markdown string to blocks and insert them ADDITIVELY (without clearing the document). Async — the converter is lazy-loaded. Returns all created nodes in document order; empty input or a dangling parentId returns [].

const nodes = await blocks.insertMarkdown(
  '# Title\n\n- one\n- two',
  { position: 'end' },
);

Serialize the WHOLE document to Markdown (async, lazy-loaded serializer). Structure Markdown can't express (e.g. merged table cells) is dropped.

const md = await blocks.exportMarkdown();

Convert Markdown to blocks WITHOUT an editor instance — the standalone `@bloklabs/core/markdown` subpath, not a method on the hook. It needs no DOM and no mounted Blok, so it is the server-side path insertMarkdown/exportMarkdown cannot cover: import Markdown in a Node job, seed a document, or precompute `data` before the editor mounts. `config` is a `MarkdownImportConfig` (tool mapping, GFM, extensions). The result is ready for `blocks.render()` or `blocks.insertMany()`.

import { markdownToBlocks } from '@bloklabs/core/markdown';

// No editor instance required — this also runs on the server
const parsed = await markdownToBlocks('# Title\n\n- one\n- two');

// -> OutputBlockData[]; store it, or hand it to a live editor
await blocks.render({ blocks: parsed });

Move a block to a flat slot: { before }, { after }, or { toIndex }. The block adopts the parent of wherever it lands — use nest/unnest to change the parent without picking a sibling slot.

blocks.move(nodeId, { after: otherId });
blocks.move(nodeId, { toIndex: 0 });

Make a block a child of another block.

blocks.nest(childId, toggleId);

Move a nested block up one level (out of its parent).

blocks.unnest(childId);

Remove a block (and its subtree).

blocks.remove(nodeId);

Update a block's data and/or tunes by id. Delegates to core's async blocks.update (its own undo step); unknown ids are a silent no-op.

blocks.update(nodeId, { text: 'Edited' });

Convert a block to another type ("turn into"). Both tools must define conversionConfig; a non-convertible block is a graceful no-op. options.caret places the caret in the converted block.

blocks.convert(nodeId, 'header', { level: 2 });

Run several mutations as ONE atomic undo step.

blocks.transact(() => {
  blocks.remove(oldId);
  blocks.insert({ type: 'paragraph', data: { text: 'Replacement' } });
});

Like transact, but the operation is NOT captured in undo history — for silent auto-repair/normalization that CMD+Z should never step through.

blocks.transactWithoutCapture(() => {
  blocks.update(nodeId, { text: normalized });
});

Atomically split a block: update the current block and insert a new one at an absolute flat index, as ONE undo step.

const newNode = blocks.splitBlock(
  nodeId, { text: 'First half' },
  'paragraph', { text: 'Second half' },
  blocks.getBlockIndex(nodeId)! + 1,
);

Insert a single child under a parent at a flat index, atomically (creation AND parent assignment in ONE undo step) — prefer over insert() + nest(), which is two steps.

const child = blocks.insertInsideParent(toggleId, 3);

Insert a flat array of already-serialized OutputBlockData (the save() shape) directly, honoring parent/content links. One atomic undo step.

const nodes = blocks.insertOutputData(savedFragment.blocks);

Replace the WHOLE document with blocks from saved OutputData — a document-LOAD primitive that clears existing content first (unlike the additive inserters).

await blocks.render(savedData);

Replace the WHOLE document with blocks parsed from an HTML string (clears existing content first).

await blocks.renderFromHTML('<h1>Imported</h1><p>Body</p>');

Remove every block from the document.

await blocks.clear();

The current block count (reactive).

const count = blocks.getBlocksCount();

The flat index of the block holding the caret, or -1 when none.

const index = blocks.getCurrentBlockIndex();

The block at a flat index as a snapshot node, or null.

const first = blocks.getBlockByIndex(0);

The absolute flat index of a block by id, or null when unknown.

const index = blocks.getBlockIndex(nodeId);

Read a block's current data and tunes by id without mutating anything — makes a client-side duplicate composable: read a node, then insert({ type, data, tunes }).

const saved = blocks.getBlockData(nodeId);
if (saved) {
  blocks.insert({ type: 'paragraph', data: saved.data, position: { after: nodeId } });
}

The block whose holder contains/equals a DOM element — maps an event target back to a block.

const node = blocks.getBlockByElement(event.target as HTMLElement);

Read a tool's default empty data without inserting anything. Rejects for an unknown tool.

const defaults = await blocks.composeBlockData('header');

Whether a Yjs sync (undo/redo) is in progress — use it to skip cleanup that would fight undo state.

if (!blocks.isSyncingFromYjs()) {
  blocks.update(nodeId, { text: cleaned });
}