Skip to main content

@lexical/extension/BlockIdExtension

Interfaces​

BlockIdConfig​

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

Experimental

Properties​

$isIdentifiedBlock​

$isIdentifiedBlock: (node) => boolean

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

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:244

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:265

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

BlockIdOutput​

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

Experimental

The output of BlockIdExtension.

Properties​

$getBlockById​

$getBlockById: (id) => LexicalNode | null

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

Experimental

The same as $getBlockById for this editor.

Parameters​
id​

string

Returns​

LexicalNode | null

$isIdentifiedBlock​

$isIdentifiedBlock: (node) => boolean

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

Experimental

The configured BlockIdConfig.$isIdentifiedBlock.

Parameters​
node​

LexicalNode

Returns​

boolean

disabled​

disabled: Signal<boolean>

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

Experimental

See BlockIdConfig.disabled.

Variables​

BlockIdExtension​

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

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

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.

blockIdState​

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

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

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:189

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:130

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.

Parameters​

id​

string

Returns​

LexicalNode | null

$getBlockId()​

$getBlockId(node): string | null

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

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:145

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

generateBlockId()​

generateBlockId(): string

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

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