@lexical/utils

DOMNodeToLexicalConversionMap

DOMNodeToLexicalConversionMap = Record<string, DOMNodeToLexicalConversion>

Defined in: packages/lexical-utils/src/index.ts:592

ObjectKlass

ObjectKlass<T> = (...args) => T

Defined in: packages/lexical-utils/src/index.ts:817

Type Parameters

T

T

Parameters

args

...any[]

Returns

T

Functions

$descendantsMatching()

$descendantsMatching<T>(children, $predicate): T[]

Defined in: packages/lexical-utils/src/index.ts:1050

A depth first traversal of the children array that stops at and collects each node that $predicate matches. This is typically used to discard invalid or unsupported wrapping nodes on a children array in the after of an DOMConversionOutput. For example, a TableNode must only have TableRowNode as children, but an importer might add invalid nodes based on caption, tbody, thead, etc. and this will unwrap and discard those.

This function is read-only and performs no mutation operations, which makes it suitable for import and export purposes but likely not for any in-place mutation. You should use $unwrapAndFilterDescendants for in-place mutations such as node transforms.

Type Parameters

T

T extends LexicalNode

Parameters

children

LexicalNode[]

The children to traverse

$predicate

(node) => node is T

Should return true for nodes that are permitted to be children of root

Returns

T[]

The children or their descendants that match $predicate

$dfs()

$dfs(startNode?, endNode?): DFSNode[]

Defined in: packages/lexical-utils/src/index.ts:191

"Depth-First Search" starts at the root/top node of a tree and goes as far as it can down a branch end before backtracking and finding a new path. Consider solving a maze by hugging either wall, moving down a branch until you hit a dead-end (leaf) and backtracking to find the nearest branching path and repeat. It will then return all the nodes found in the search in an array of objects. Preorder traversal is used, meaning that nodes are listed in the order of when they are FIRST encountered.

Children-only spine: named slot subtrees are skipped. Use $dfsWithSlots when you need to descend into slots (e.g. character counting, slot-aware content extraction).

Parameters

startNode?

The node to start the search (inclusive), if omitted, it will start at the root node.

endNode?

The node to end the search (inclusive), if omitted, it will find all descendants of the startingNode. If endNode is an ElementNode, it will stop before visiting any of its children.

Returns

An array of objects of all the nodes found by the search, including their depth into the tree. {depth: number, node: LexicalNode} It will always return at least 1 node (the start node).

$dfsIterator()

$dfsIterator(startNode?, endNode?): IterableIterator<DFSNode>

Defined in: packages/lexical-utils/src/index.ts:249

$dfs iterator (left to right). Tree traversal is done on the fly as new values are requested with O(1) memory. Preorder traversal is used, meaning that nodes are iterated over in the order of when they are FIRST encountered.

Children-only spine: named slot subtrees are skipped. Use $dfsWithSlotsIterator (or $dfsWithSlots) when you need to descend into slots — e.g. character counting, content extraction, or any cross-tree analysis where slotted content should be visited.

Parameters

startNode?

The node to start the search (inclusive), if omitted, it will start at the root node.

endNode?

The node to end the search (inclusive), if omitted, it will find all descendants of the startingNode. If endNode is an ElementNode, the iterator will end as soon as it reaches the endNode (no children will be visited).

Returns

IterableIterator<DFSNode>

An iterator, each yielded value is a DFSNode. It will always return at least 1 node (the start node).

$dfsWithSlots()

$dfsWithSlots(startNode?, endNode?): DFSNode[]

Defined in: packages/lexical-utils/src/index.ts:269

Experimental

Like $dfs, but also descends into named slots. Slots are not on the linked-list spine, so each host's slot subtrees are emitted slots-first, right after the host node and before its linked-list children.

Parameters

startNode?

The node to start the search (inclusive), defaults to the root node.

endNode?

The node to end the search (inclusive), defaults to all descendants of startNode. Like $dfs, reaching endNode stops the traversal before visiting any of its children — including its slot subtrees. An endNode strictly inside a slot subtree is never reached (slot subtrees are spliced in whole), so it does not truncate the traversal.

Returns

An array of DFSNodes. It will always return at least 1 node (the start node).

$dfsWithSlotsIterator()

$dfsWithSlotsIterator(startNode?, endNode?): IterableIterator<DFSNode>

Defined in: packages/lexical-utils/src/index.ts:289

Experimental

Slot-aware $dfsIterator: a host's slot subtrees are emitted slots-first, right after the host node and before its linked-list children. The caret iterator drives the linked-list spine untouched.

Parameters

startNode?

The node to start the search (inclusive), defaults to the root node.

endNode?

Returns

IterableIterator<DFSNode>

An iterator, each yielded value is a DFSNode. It will always return at least 1 node (the start node).

$filter()

$filter<T>(nodes, filterFn): T[]

Defined in: packages/lexical-utils/src/index.ts:871

Type Parameters

T

T

Parameters

nodes

LexicalNode[]

Array of nodes that needs to be filtered

filterFn

(node) => T | null

A filter function that returns node if the current node satisfies the condition otherwise null

Returns

T[]

Array of filtered nodes

Deprecated

Use Array filter or flatMap

Filter the nodes

$firstToLastIterator()

$firstToLastIterator(node): Iterable<LexicalNode>

Defined in: packages/lexical-utils/src/index.ts:1080

Return an iterator that yields each child of node from first to last, taking care to preserve the next sibling before yielding the value in case the caller removes the yielded node.

Parameters

node

The node whose children to iterate

Returns

Iterable<LexicalNode>

An iterator of the node's children

$getAdjacentCaret()

$getAdjacentCaret<D>(caret): SiblingCaret<LexicalNode, D> | null

Defined in: packages/lexical-utils/src/index.ts:204

Get the adjacent caret in the same direction

Type Parameters

D

D extends CaretDirection

Parameters

caret

NodeCaret<D> | null

A caret or null

Returns

SiblingCaret<LexicalNode, D> | null

caret.getAdjacentCaret() or null

$getDepth()

$getDepth(node): number

Defined in: packages/lexical-utils/src/index.ts:399

Parameters

node

LexicalNode | null

Returns

number

$getNearestBlockElementAncestorOrThrow()

$getNearestBlockElementAncestorOrThrow(startNode): ElementNode

Defined in: packages/lexical-utils/src/index.ts:573

Returns the element node of the nearest ancestor, otherwise throws an error.

Parameters

startNode

The starting node of the search

Returns

The ancestor node found

$getNearestNodeOfType()

$getNearestNodeOfType<T>(node, klass): T | null

Defined in: packages/lexical-utils/src/index.ts:551

Takes a node and traverses up its ancestors (toward the root node) in order to find a specific type of node.

Type Parameters

T

T extends ElementNode

Parameters

node

the node to begin searching.

klass

Klass<T>

an instance of the type of node to look for.

Returns

T | null

the node of type klass that was passed, or null if none exist.

$getNextRightPreorderNode()

$getNextRightPreorderNode(startingNode): LexicalNode | null

Defined in: packages/lexical-utils/src/index.ts:420

Performs a right-to-left preorder tree traversal. From the starting node it goes to the rightmost child, than backtracks to parent and finds new rightmost path. It will return the next node in traversal sequence after the startingNode. The traversal is similar to $dfs functions above, but the nodes are visited right-to-left, not left-to-right.

Parameters

startingNode

The node to start the search.

Returns

LexicalNode | null

The next node in pre-order right to left traversal sequence or null, if the node does not exist

$getNextSiblingOrParentSibling()

$getNextSiblingOrParentSibling(node): [LexicalNode, number] | null

Defined in: packages/lexical-utils/src/index.ts:390

Returns the Node sibling when this exists, otherwise the closest parent sibling. For example R -> P -> T1, T2 -> P2 returns T2 for node T1, P2 for node T2, and null for node P2.

Parameters

node

LexicalNode.

Returns

[LexicalNode, number] | null

An array (tuple) containing the found Lexical node and the depth difference, or null, if this node doesn't exist.

$handleIndentAndOutdent()

$handleIndentAndOutdent(indentOrOutdent): boolean

Defined in: packages/lexical-utils/src/index.ts:892

Applies the provided callback to each indentable block element in the Selection

Parameters

indentOrOutdent

(block) => void

callback for performing the indent or outdent action on a given block element.

Returns

boolean

true if at least one block was handled, false otherwise.

$insertFirst()

$insertFirst(parent, node): void

Defined in: packages/lexical-utils/src/index.ts:929

Appends the node before the first child of the parent node

Parameters

parent

A parent node

node

Node that needs to be appended

Returns

void

$insertNodeIntoLeaf()

$insertNodeIntoLeaf(node): void

Defined in: packages/lexical-utils/src/index.ts:775

Inserts a node into leaf — the deepest accessible node at the carriage position

Parameters

node

The node to be inserted

Returns

void

$insertNodeToNearestRoot()

$insertNodeToNearestRoot<T>(node): T

Defined in: packages/lexical-utils/src/index.ts:729

If the selected insertion area is the root/shadow root node (see $isRootOrShadowRoot), the node will be appended there, otherwise, it will be inserted before the insertion area. If there is no selection where the node is to be inserted, it will be appended after any current nodes within the tree, as a child of the root node. A paragraph will then be added after the inserted node and selected.

Type Parameters

T

T extends LexicalNode

Parameters

node

T

The node to be inserted

Returns

T

The node after its insertion

$isAtEndOfNode()

$isAtEndOfNode(point, node): boolean

Defined in: packages/lexical-utils/src/index.ts:1328

Whether the collapsed point sits at the very end of node's content — on its last descendant (or on the empty node itself) at that node's end. Shared by $onEscapeDown and slot-aware variants so the "at the trailing edge of a container" test stays in one place.

Parameters

point

PointType

node

Returns

boolean

$isAtStartOfNode()

$isAtStartOfNode(point, node): boolean

Defined in: packages/lexical-utils/src/index.ts:1318

Whether the collapsed point sits at the very start of node's content — on its first descendant (or on the empty node itself) at offset 0. Shared by $onEscapeUp and slot-aware variants so the "at the leading edge of a container" test stays in one place.

Parameters

point

PointType

node

Returns

boolean

$isEditorIsNestedEditor()

$isEditorIsNestedEditor(editor): boolean

Defined in: packages/lexical-utils/src/index.ts:985

Checks if the editor is a nested editor created by LexicalNestedComposer

Parameters

editor

Returns

boolean

$lastToFirstIterator()

$lastToFirstIterator(node): Iterable<LexicalNode>

Defined in: packages/lexical-utils/src/index.ts:1092

Return an iterator that yields each child of node from last to first, taking care to preserve the previous sibling before yielding the value in case the caller removes the yielded node.

Parameters

node

The node whose children to iterate

Returns

Iterable<LexicalNode>

An iterator of the node's children

$onEscapeDown()

$onEscapeDown($isContainerNode, event?): boolean

Defined in: packages/lexical-utils/src/index.ts:1284

Inserts a new paragraph after a container node when the cursor moves outside the container element

Intended for use ArrowRight/ArrowDown keyboard handlers to allow the user to break out of a container node by creating a new paragraph after it.

A paragraph is inserted if that the cursor is positioned at the ending inside the container, and the container itself is the last element in the document and has no next sibling

When a paragraph is inserted the selection is moved to it and, if the triggering keyboard event is provided, its default action is prevented so the browser does not additionally move the selection. Relying on the native caret movement is not portable: Chromium moves into the freshly inserted paragraph while Firefox leaves the caret inside the container.

Parameters

$isContainerNode

(node?) => node is ElementNode

Type guard identifying the container node type to escape from.

event?

KeyboardEvent | null

The keyboard event that triggered the escape, if any. Its default action is prevented when a paragraph is inserted.

Returns

boolean

true if a paragraph was inserted, false otherwise.

$onEscapeUp()

$onEscapeUp($isContainerNode, event?): boolean

Defined in: packages/lexical-utils/src/index.ts:1235

Inserts a new paragraph before a container node when the cursor moves outside the container element

Intended for use ArrowLeft/ArrowUp keyboard handlers to allow the user to break out of a container node by creating a new paragraph before it.

A paragraph is inserted if that the cursor is positioned at the beginning inside the container, and the container itself is the first element in the document and has no preceding sibling

Parameters

$isContainerNode

(node?) => node is ElementNode

Type guard identifying the container node type to escape from.

event?

KeyboardEvent | null

The keyboard event that triggered the escape, if any. Its default action is prevented when a paragraph is inserted.

Returns

boolean

true if a paragraph was inserted, false otherwise.

$restoreEditorState()

$restoreEditorState(editor, editorState): void

Defined in: packages/lexical-utils/src/index.ts:687

Clones the editor and marks it as dirty to be reconciled. If there was a selection, it would be set back to its previous state, or null otherwise.

Parameters

editor

The lexical editor

editorState

EditorState

The editor's state

Returns

void

$reverseDfs()

$reverseDfs(startNode?, endNode?): DFSNode[]

Defined in: packages/lexical-utils/src/index.ts:228

Right-to-left mirror of $dfs. It returns all the nodes found in the search in an array of objects. Preorder traversal is used, meaning that nodes are listed in the order of when they are FIRST encountered.

Children-only spine: named slot subtrees are skipped. Use $reverseDfsWithSlots when you need to descend into slots (e.g. character counting, slot-aware content extraction).

The whole traversal is materialized. Use $reverseDfsIterator to walk it on the fly with O(1) memory.

Parameters

startNode?

The node to start the search (inclusive), if omitted, it will start at the root node.

endNode?

The node to end the search (inclusive), if omitted, it will find all descendants of the startingNode. If endNode is an ElementNode, it will stop before visiting any of its children.

Returns

An array of objects of all the nodes found by the search, including their depth into the tree. {depth: number, node: LexicalNode} It will always return at least 1 node (the start node).

$reverseDfsIterator()

$reverseDfsIterator(startNode?, endNode?): IterableIterator<DFSNode>

Defined in: packages/lexical-utils/src/index.ts:436

$dfs iterator (right to left). Tree traversal is done on the fly as new values are requested with O(1) memory.

Parameters

startNode?

The node to start the search, if omitted, it will start at the root node.

endNode?

The node to end the search, if omitted, it will find all descendants of the startingNode.

Returns

IterableIterator<DFSNode>

An iterator, each yielded value is a DFSNode. It will always return at least 1 node (the start node).

$reverseDfsWithSlots()

$reverseDfsWithSlots(startNode?, endNode?): DFSNode[]

Defined in: packages/lexical-utils/src/index.ts:455

Experimental

Like $reverseDfs, but also descends into named slots. Mirror of $dfsWithSlots.

Parameters

startNode?

The node to start the search (inclusive), defaults to the root node.

endNode?

The node to end the search (inclusive), defaults to all descendants of startNode. Mirroring $dfsWithSlots, reaching endNode stops the traversal without emitting its slot subtrees. An endNode strictly inside a slot subtree is never reached (slot subtrees are spliced in whole), so it does not truncate the traversal.

Returns

An array of DFSNodes. It will always return at least 1 node (the start node).

$reverseDfsWithSlotsIterator()

$reverseDfsWithSlotsIterator(startNode?, endNode?): IterableIterator<DFSNode>

Defined in: packages/lexical-utils/src/index.ts:478

Experimental

Right-to-left mirror of $dfsWithSlotsIterator. Forward visits slots before children, so the mirror visits them last: a host's slot subtrees are emitted (in reverse slot order) only once its linked-list subtree is fully traversed. Because the caret spine streams nodes, "left the host subtree" is detected when a node at the host's depth or shallower arrives, flushing the host's pending slots. The caret iterator drives the spine untouched.

Parameters

startNode?

The node to start the search (inclusive), defaults to the root node.

endNode?

The node to end the search (inclusive), defaults to all descendants of startNode. Mirroring $dfsWithSlotsIterator, reaching endNode stops the traversal without emitting its slot subtrees. An endNode strictly inside a slot subtree is never reached (slot subtrees are spliced in whole), so it does not truncate the traversal.

Returns

IterableIterator<DFSNode>

An iterator, each yielded value is a DFSNode. It will always return at least 1 node (the start node).

$unwrapAndFilterDescendants()

$unwrapAndFilterDescendants(root, $predicate): boolean

Defined in: packages/lexical-utils/src/index.ts:1000

A depth first last-to-first traversal of root that stops at each node that matches $predicate and ensures that its parent is root. This is typically used to discard invalid or unsupported wrapping nodes. For example, a TableNode must only have TableRowNode as children, but an importer might add invalid nodes based on caption, tbody, thead, etc. and this will unwrap and discard those.

Parameters

root

The root to start the traversal

$predicate

(node) => boolean

Should return true for nodes that are permitted to be children of root

Returns

boolean

true if this unwrapped or removed any nodes

$unwrapNode()

$unwrapNode(node): void

Defined in: packages/lexical-utils/src/index.ts:1125

Replace this node with its children

Parameters

node

The ElementNode to unwrap and remove

Returns

void

$wrapNodeInElement()

$wrapNodeInElement<T>(node, createElementNode): T

Defined in: packages/lexical-utils/src/index.ts:806

Wraps the node into another node created from a createElementNode function, eg. $createParagraphNode

Type Parameters

T

T extends ElementNode

Parameters

node

Node to be wrapped.

createElementNode

() => T

Creates a new lexical element to wrap the to-be-wrapped node and returns it.

Returns

T

A new lexical element with the previous node appended within (as a child, including its children).

calculateZoomLevel()

calculateZoomLevel(element, useManualZoom?): number

Defined in: packages/lexical-utils/src/index.ts:964

Calculates the zoom level of an element as a result of using css zoom property. For browsers that implement standardized CSS zoom (Firefox, Chrome >= 128), this will always return 1.

Parameters

element

Element | null

useManualZoom?

boolean = false

If true, always use zoom level will be calculated manually, otherwise it will be calculated on as needed basis.

Returns

number

dedupeSelectionRects()

dedupeSelectionRects<Rect>(rects): Rect[]

Defined in: packages/lexical-utils/src/dedupeSelectionRects.ts:51

Dedupe a list of selection client-rects before they are drawn as fills.

Range.getClientRects() can return rects that are duplicated or contained within another, and WebKit in particular emits a spurious wider rect alongside the real text rect on some blocks (balanced or letter-spaced headings are the reproducible case). Drawn as semi-transparent fills, duplicates read brighter than a single rect, and the wider rect paints the "extra empty selection area" reported in facebook/lexical#7106.

This drops zero-area rects and any rect that contains another, keeping the smaller text-hugging one, with a 1px tolerance for sub-pixel jitter. The assumption is that genuine same-line rects are horizontally disjoint (one rect per visual row; inline boxes on a row tile side by side), so containment only holds for the duplicate or spurious-wider cases, never for a legitimate sub-fragment that should be kept.

On the createRectsFromDOMRange path (e.g. positionNodeOnRange): that helper's own selectionSpansElement filter already drops the full-block-width spurious rect, so there this mainly prevents the duplicate-doubling. The #7106 extra-area paint is addressed for consumers that feed raw getClientRects(), where selectionSpansElement does not run — that is the path that needs it.

Known limitation: the disjoint assumption holds for normal flow. Overlapping inline content — a negative margin, a transform, or a baseline-shifted inline decorator — can place a real sub-fragment inside a wider real-text rect on the same row; if a sub-pixel top offset also lets both clear createRectsFromDOMRange's asymmetric overlap filter, keep-smaller drops the wider rect and under-paints the glyphs it uniquely covered. There is no rect-only fix: that wider rect is geometrically indistinguishable from the spurious-wider (#7106) rect, so keeping it would re-introduce the extra-area paint. See the under-paint characterization browser test.

Typed on the structural subset of DOMRect it reads, so it accepts a live DOMRectList from getClientRects() as well as the DOMRect[] returned by createRectsFromDOMRange, and is unit-testable without a DOM.

Type Parameters

Rect

Rect extends RectLike

Parameters

rects

Iterable<Rect>

Returns

Rect[]

eventFiles()

eventFiles(event): [boolean, File[], boolean]

Defined in: packages/lexical-utils/src/index.ts:841

Parameters

event

DragEvent | PasteCommandType

Returns

[boolean, File[], boolean]

getScrollParent()

getScrollParent(element, includeHidden): HTMLElement | HTMLBodyElement

Defined in: packages/lexical-utils/src/getScrollParent.ts:23

Walks up from element and returns the nearest scrollable ancestor (or ownerDocument.body if none is found), used to keep the active typeahead option scrolled into view. Set includeHidden to also treat overflow: hidden ancestors as scroll parents.

The walk crosses ShadowRoot→host (via getParentElement) so a shadow-mounted editor's scroll parent is found in the enclosing light-DOM ancestor chain, and the styles / body are resolved through the element's own realm so an iframe-mounted editor stays inside its document.

Parameters

element

HTMLElement

includeHidden

boolean

Returns

HTMLElement | HTMLBodyElement

isMimeType()

isMimeType(file, acceptableMimeTypes): boolean

Defined in: packages/lexical-utils/src/index.ts:118

Returns true if the file type matches the types passed within the acceptableMimeTypes array, false otherwise. The types passed must be strings and are CASE-SENSITIVE. eg. if file is of type 'text' and acceptableMimeTypes = ['TEXT', 'IMAGE'] the function will return false.

Parameters

file

File

The file you want to type check.

acceptableMimeTypes

string[]

An array of strings of types which the file is checked against.

Returns

boolean

true if the file is an acceptable mime type, false otherwise.

makeStateWrapper()

makeStateWrapper<K, V>(stateConfig): StateConfigWrapper<K, V>

Defined in: packages/lexical-utils/src/index.ts:1192

EXPERIMENTAL

A convenience interface for working with $getState and $setState.

Type Parameters

K

K extends string

V

V

Parameters

stateConfig

StateConfig<K, V>

The stateConfig to wrap with convenience functionality

Returns

StateConfigWrapper<K, V>

a StateWrapper

markSelection()

markSelection(editor, onReposition?): () => void

Defined in: packages/lexical-utils/src/markSelection.ts:98

Place one or multiple newly created Nodes at the current selection. Multiple nodes will only be created when the selection spans multiple lines (aka client rects).

This function can come useful when you want to show the selection but the editor has been focused away.

Parameters

editor

onReposition?

(node) => void

Returns

() => void

mediaFileReader()

mediaFileReader(files, acceptableMimeTypes): Promise<object[]>

Defined in: packages/lexical-utils/src/index.ts:138

Lexical File Reader with:

MIME type support
batched results (HistoryPlugin compatibility)
Order aware (respects the order when multiple Files are passed)

const filesResult = await mediaFileReader(files, ['image/']); filesResult.forEach(file => editor.dispatchCommand('INSERT_IMAGE', { src: file.result, }));

Parameters

files

File[]

acceptableMimeTypes

string[]

Returns

Promise<object[]>

objectKlassEquals()

objectKlassEquals<T>(object, objectClass): object is T

Defined in: packages/lexical-utils/src/index.ts:824

Type Parameters

T

T

Parameters

object

unknown

= The instance of the type

objectClass

ObjectKlass<T>

= The class of the type

Returns

object is T

Whether the object is has the same Klass of the objectClass, ignoring the difference across window (e.g. different iframes)

positionNodeOnRange()

positionNodeOnRange(editor, range, onReposition): () => void

Defined in: packages/lexical-utils/src/positionNodeOnRange.ts:39

Place one or multiple newly created Nodes at the passed Range's position. Multiple nodes will only be created when the Range spans multiple lines (aka client rects).

This function can come particularly useful to highlight particular parts of the text without interfering with the EditorState, that will often replicate the state across collab and clipboard.

This function accounts for DOM updates which can modify the passed Range. Hence, the function return to remove the listener.

Parameters

editor

range

Range

onReposition

(node) => void

Returns

() => void

registerNestedElementResolver()

registerNestedElementResolver<N>(editor, targetNode, cloneNode, handleOverlap): () => void

Defined in: packages/lexical-utils/src/index.ts:606

Attempts to resolve nested element nodes of the same type into a single node of that type. It is generally used for marks/commenting

Type Parameters

N

N extends ElementNode

Parameters

editor

The lexical editor

targetNode

Klass<N>

The target for the nested element to be extracted from.

cloneNode

(from) => N

See $createMarkNode

handleOverlap

(from, to) => void

Handles any overlap between the node to extract and the targetNode

Returns

The lexical editor

() => void

selectionAlwaysOnDisplay()

selectionAlwaysOnDisplay(editor, onReposition?): () => void

Defined in: packages/lexical-utils/src/selectionAlwaysOnDisplay.ts:18

Parameters

editor