Skip to main content

@lexical/extension/BlockIdExtension

Interfaces​

BlockIdConfig​

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:370

Experimental

Properties​

$isIdentifiedBlock​

$isIdentifiedBlock: (node) => boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:385

Experimental

Which nodes get an id. Evaluated when a node is marked dirty, so it should depend only on the node and its ancestors. Default: $defaultIsIdentifiedBlock (the root's children, nested blocks that hold text, and nested block decorators). Every reader of a document stored without ids must use the same predicate, since positional ids follow from it.

Parameters​
node​

LexicalNode

Returns​

boolean

disabled​

disabled: boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:376

Experimental

Set to true to stop assigning, repairing, and indexing ids. Ids already stored on nodes are kept. While disabled, $getBlockById falls back to a scan of the document.

generateId​

generateId: () => string

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:397

Experimental

Makes a new id. It must return 1 to 64 characters of the base64url alphabet (A–Z, a–z, 0–9, -, _). A value that is invalid or already used in this editor is discarded and generateId is called again; 32 such values in a row throw. Ids made concurrently by independent writers cannot see each other, so a replacement must stay unique across writers (random ids of 120 bits or more, or a per-writer prefix). Tests can inject a deterministic counter. Default: generateBlockId.

Returns​

string

repairTransforms​

repairTransforms: boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:409

Experimental

Whether the follow-up update that names the blocks an update applied with skipTransforms, or tagged COLLABORATION_TAG or HISTORIC_TAG, left without a valid id or with a repeated one runs the editor's transforms. With true (the default) it marks those blocks dirty, so every transform runs on them, and NodeStructureExtension, for example, repairs their structure in it. With false it sets their ids without running transforms, so it changes nothing else: for code that applies such updates and repairs or otherwise processes what they bring in an update of its own.

BlockIdOutput​

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:417

Experimental

The output of BlockIdExtension.

Properties​

$getBlockById​

$getBlockById: (id) => LexicalNode | null

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:421

Experimental

The same as $getBlockById for this editor.

Parameters​
id​

string

Returns​

LexicalNode | null

$getBlockHandle​

$getBlockHandle: (node) => string | null

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:423

Experimental

The same as $getBlockHandle for this editor.

Parameters​
node​

LexicalNode

Returns​

string | null

$getBlockHandles​

$getBlockHandles: () => Map<string, string>

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:425

Experimental

The same as $getBlockHandles for this editor.

Returns​

Map<string, string>

$isIdentifiedBlock​

$isIdentifiedBlock: (node) => boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:429

Experimental

The configured BlockIdConfig.$isIdentifiedBlock.

Parameters​
node​

LexicalNode

Returns​

boolean

$resolveBlockHandle​

$resolveBlockHandle: (handle) => BlockHandleResult

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:427

Experimental

The same as $resolveBlockHandle for this editor.

Parameters​
handle​

string

Returns​

BlockHandleResult

disabled​

disabled: Signal<boolean>

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:419

Experimental

See BlockIdConfig.disabled.

Type Aliases​

BlockHandleResult​

BlockHandleResult = { node: LexicalNode; status: "found"; } | { handle: string; status: "not-found"; } | { candidates: readonly string[]; handle: string; status: "ambiguous"; } | { handle: string; status: "invalid"; }

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:184

Experimental

What $resolveBlockHandle found for a handle:

  • found: the one identified block that the handle names.
  • not-found: no identified block's id starts with it (a mistyped handle, or a block deleted since the handle was read).
  • ambiguous: several do (a block whose id shares the prefix was added since the handle was read). candidates holds their current handles, in ascending order, at most 10.
  • invalid: not 1 to 64 characters of the base64url alphabet, so neither a handle nor an id.

Variables​

BlockIdExtension​

const BlockIdExtension: LexicalExtension<BlockIdConfig, "@lexical/extension/BlockId", BlockIdOutput, unknown>

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:1705

Experimental

Gives blocks stable ids, stored as NodeState (blockIdState), so that code outside the editor (an AI agent, a server pipeline, a comment system) can address a block by id across sessions, replicas, and serializations.

Every identified block gets an id in the update that creates it. A document stored without ids gets positional ids, which every reader and replica derives alike; blocks created by edits get random ids (generateBlockId). Ids are unique: a copy yields to the block it was copied from. By default the root's children, nested blocks that hold text, and nested block decorators are identified ($defaultIsIdentifiedBlock). While enabled, $getBlockById looks blocks up in an index maintained from the dirty nodes of each update. See the Block IDs documentation page for the exact rules.

Showing blocks to a model? Use handles, the shortest unique prefix of each id (4 characters or more), instead of whole ids: $getBlockHandle / $resolveBlockHandle, or export: 'handle' in BlockIdHTMLExtension. A mistyped or outdated handle almost always resolves as not found or ambiguous rather than as another block.

blockIdState​

const blockIdState: StateConfig<"blockId", string | undefined>

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:112

Experimental

The NodeState that stores a block's id, serialized in node JSON as "$": {"blockId": "..."}.

It is ordinary NodeState, so it survives clones and undo, round-trips through exportJSON/importJSON, and is carried by anything that copies NodeState. It is reset by $copyNode, so a node split off another one (e.g. the new ListItemNode that Enter creates) starts without an id instead of with a duplicate.

A valid id is 1 to 64 characters of the base64url alphabet (A–Z, a–z, 0–9, -, _). Anything else reads as "no id", so the block gets a new one as if it had none.

Functions​

$defaultIsIdentifiedBlock()​

$defaultIsIdentifiedBlock(node): boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:321

Experimental

The default BlockIdConfig.$isIdentifiedBlock:

  • every element and decorator child of the root ($isRootChildBlock), so a top-level list or table has an id too;
  • every nested block that holds text: a non-inline element whose class declares children: 'inline' in $config() (or a list that includes 'inline'), such as a paragraph, heading, quote or code block in a table cell, or a list item;
  • every nested non-inline decorator.

Nested wrappers get no id: nested lists, table rows and cells, shadow roots (a shadow root quote holds blocks, whatever its class declares), and nested elements whose class declares no children. A slot is nested like a shadow root, so blocks in slots follow the same rules. Compose it to identify more:

configExtension(BlockIdExtension, {
  $isIdentifiedBlock: (node) =>
    $defaultIsIdentifiedBlock(node) || $isTableCellNode(node),
});

Parameters​

node​

LexicalNode

Returns​

boolean

$getBlockById()​

$getBlockById(id): LexicalNode | null

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:166

Experimental

Returns the identified block with the given id in the active editor state, or null. Requires BlockIdExtension.

The lookup goes through an index kept up to date from the dirty nodes of each commit and is verified against the active state, so it never returns a stale node. A block created, replaced or re-keyed earlier in the same update is found once that update has committed: after $getBlockById(id).replace(node), look the id up again in a later update. The match is exact: a prefix of an id finds nothing.

Showing blocks to a model? Use handles, which cost a few tokens instead of a whole id: $getBlockHandle / $resolveBlockHandle, or export: 'handle' in BlockIdHTMLExtension.

// What the model reads: [{block: 'V1St', text: 'Q3 plan'}, ...]
const blocks = editor.read(() =>
  $getRoot()
    .getChildren()
    .map(node => ({block: $getBlockHandle(node), text: node.getTextContent()})),
);
// What it answers: {block: 'V1St', text: 'Q4 plan'}
editor.update(() => {
  const result = $resolveBlockHandle(op.block);
  if (result.status === 'found') {
    result.node.replace($createParagraphNode().append($createTextNode(op.text)));
  }
});

Parameters​

id​

string

Returns​

LexicalNode | null

$getBlockHandle()​

$getBlockHandle(node): string | null

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:219

Experimental

Returns the handle of an identified block: the shortest prefix of its id, at least MIN_BLOCK_HANDLE_LENGTH characters long, that no other identified block's id starts with, like a short git hash (V1St for V1StGXR8_Z5jdHi6B-myT). An id shorter than that, or one that another id starts with, is its own handle. Returns null for a node that has no id or that $getBlockById would not find by its id (one that is not attached or not an identified block, a block named since the last commit, or a copy whose repeated id awaits its repair). Requires BlockIdExtension.

Handles are for showing blocks to a model at a fraction of the tokens of a whole id: $resolveBlockHandle takes them back. They are derived from the ids of the document, never stored, so a handle can grow longer when a block whose id shares its prefix is added. A handle read earlier then resolves as ambiguous rather than to either block, unless the new block's whole id is the handle (an exact id always wins).

Handles are computed from the same blocks as $getBlockById: those of the last committed state while the extension is enabled (all of them at once, then cached until the next commit changes an id), and a scan of the document on each call while it is disabled.

Parameters​

node​

LexicalNode

Returns​

string | null

$getBlockHandles()​

$getBlockHandles(): Map<string, string>

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:230

Experimental

Returns the handle of every identified block, by id (see $getBlockHandle). The map is a new one on each call. Requires BlockIdExtension.

Returns​

Map<string, string>

$getBlockId()​

$getBlockId(node): string | null

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:127

Experimental

Returns the id stored on node, or null if it has none.

This reads the NodeState directly, so it also returns an id left on a node that is not an identified block (a top-level list that indenting nested into a list item, say); such ids are not indexed and $getBlockById does not find them.

Parameters​

node​

LexicalNode

Returns​

string | null

$isRootChildBlock()​

$isRootChildBlock(node): boolean

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:277

Experimental

A BlockIdConfig.$isIdentifiedBlock that identifies every element and decorator child of the root, and nothing nested. Use it when only top-level blocks are addressed:

configExtension(BlockIdExtension, {$isIdentifiedBlock: $isRootChildBlock});

Parameters​

node​

LexicalNode

Returns​

boolean

$resolveBlockHandle()​

$resolveBlockHandle(handle): BlockHandleResult

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:262

Experimental

Finds the identified block that a handle from $getBlockHandle names, for input that cannot be trusted (a language model's answer): it reports a mistyped, outdated or invalid handle in a BlockHandleResult instead of throwing. It returns a block only when exactly one block's id starts with the handle (or equals it). Requires BlockIdExtension.

A whole id is accepted too, and an exact match wins (b1 finds the block b1 even when b12 exists). Otherwise the handle must be at least MIN_BLOCK_HANDLE_LENGTH characters long and the start of exactly one block's id. A handle that was longer when it was read (another id shared its prefix then) still finds its block.

A handle names whichever block's id starts with it now, not the block it was read from: after local, remote or concurrent changes, a handle read earlier resolves as not-found or ambiguous, or, if its block was deleted and a new block's id starts with the same prefix, as that new block. With random ids that takes a new id sharing the first 4 characters, about one chance in 16.7 million per new block. Where an edit must reach the block that was read, keep the ids of the read ($getBlockHandles maps them to handles) and check $getBlockId(result.node) against them, or look them up with $getBlockById. Like $getBlockById, a block created earlier in the same update is found once that update has committed.

Parameters​

handle​

string

Returns​

BlockHandleResult

generateBlockId()​

generateBlockId(): string

Defined in: packages/lexical-extension/src/BlockIdExtension.ts:353

Experimental

The default BlockIdConfig.generateId: 21 characters of the base64url alphabet (126 random bits, more than the 122 of a version 4 UUID), from crypto.getRandomValues. Ids need no coordination between independent writers (replicas, servers, agents): ids made independently practically never collide, and a mistyped id (from a language model, say) almost never names another block.

There is no weaker fallback: where crypto.getRandomValues is missing (React Native without a polyfill, for instance), it throws, and the editor must be given a generateId of its own.

Returns​

string

References​

MIN_BLOCK_HANDLE_LENGTH​

Re-exports MIN_BLOCK_HANDLE_LENGTH