@lexical/html

Interfaces

AttrMatchOptions

Defined in: packages/lexical-html/src/import/types.ts:72

Experimental

Options bag for ElementSelectorBuilder.attr when the value is a regex. Future options will be added here without breaking existing call-sites.

Type Parameters

K

K extends string = string

Properties

capture?

readonly optional capture?: K

Defined in: packages/lexical-html/src/import/types.ts:78

Experimental

If provided, the RegExpMatchArray from the successful match is stored on ctx.captures[capture] for the importer to consume — saving a second regex execution.

---

ChildSchema

Defined in: packages/lexical-html/src/import/types.ts:293

Experimental

A ChildSchema encodes which lexical nodes a parent accepts as children and how to package or reject the rest. The legacy wrapContinuousInlines / ArtificialNode__DO_NOT_USE logic is the BlockSchema and NestedBlockSchema cases of this primitive.

A schema only controls how the children are assembled before being appended to the parent the calling rule already chose. It cannot change the parent itself. Cases where the parent's shape needs to change in response to its children — e.g. an inline <a> that encloses a block <h1>, which must be lifted so the heading takes the link's place and the link is redistributed onto the heading's inline contents — belong in the rule body, not the schema. See the "Lifting blocks out of an inline parent" section of the docs.

Properties

name?

readonly optional name?: string

Defined in: packages/lexical-html/src/import/types.ts:295

Experimental

Optional name for debug output.

onReject?

readonly optional onReject?: "drop" | "hoist"

Defined in: packages/lexical-html/src/import/types.ts:331

Experimental

Fallback strategy for a run of non-accepted children when $packageRun is missing or returns an empty array:

• 'drop' (default) — silently discards the run. Use when the schema is strict and rejected content is meaningless in this position (e.g. text between table rows).
• 'hoist' — emits the rejected nodes unchanged at the same position in the assembled child list. The caller's parent then receives them as-is, which is only useful if the calling rule intends to surface mixed content to its parent (a less common pattern; usually $packageRun should re-shape the run first).

'hoist' does NOT lift the run all the way up out of the calling rule's parent — that requires the rule itself to detect the situation and emit a different parent structure (see the "Lifting blocks out of an inline parent" section).

Methods

$accepts()

$accepts(child, parent): boolean

Defined in: packages/lexical-html/src/import/types.ts:299

Experimental

Returns true if child is a valid child of parent in this position.

Parameters

child

LexicalNode

parent

LexicalNode | null

Returns

boolean

$finalize()?

optional $finalize(children, parent): LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:337

Experimental

Final pass over the assembled child list (after $packageRun). Returns the children to actually attach. Use to enforce structural invariants (e.g. drop empty runs, pad short table rows).

Parameters

children

LexicalNode[]

parent

LexicalNode | null

Returns

LexicalNode[]

$packageRun()?

optional $packageRun(rejected, parent, domParent): LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:308

Experimental

Package a maximal run of non-accepted siblings into zero or more accepted nodes. The returned nodes replace the rejected run at the same position in the child list and are not re-checked against $accepts — the caller is trusted to return valid children. If omitted, or if it returns an empty array, ChildSchema.onReject is consulted instead.

Parameters

rejected

LexicalNode[]

parent

LexicalNode | null

domParent

Node | null

Returns

LexicalNode[]

---

CompiledOverlayRules

Defined in: packages/lexical-html/src/import/defineOverlayRules.ts:28

Experimental

Opaque handle for a pre-compiled set of overlay rules. Produce one with defineOverlayRules and pass it to DOMImportContext.$importChildren via ImportChildrenOpts.rules.

To merge two or more overlays into a single one, pass them (alongside raw DOMImportRules if desired) to a fresh defineOverlayRules — earlier arguments are higher priority.

The internal shape is intentionally not part of the public API: it's a compiled dispatch table tagged with __type so callers cannot pass a raw rule array where a compiled overlay is expected.

Properties

__type

readonly __type: "CompiledOverlayRules"

Defined in: packages/lexical-html/src/import/defineOverlayRules.ts:29

Experimental

---

CompiledSelector

Defined in: packages/lexical-html/src/import/types.ts:38

Experimental

An opaque, compiled selector used as the match field of a DOMImportRule. The two phantom type parameters carry the matched Node subtype (N) and a record of named regex captures (C) so the importer body gets correctly-typed ctx and node arguments without casts.

Extended by

• ElementSelectorBuilder

Type Parameters

N

N extends Node = Node

C

C extends Record<string, RegExpMatchArray> = Record<string, RegExpMatchArray>

Properties

[CaptureBrand]?

readonly optional [CaptureBrand]?: C

Defined in: packages/lexical-html/src/import/types.ts:43

Experimental

[NodeBrand]?

readonly optional [NodeBrand]?: N

Defined in: packages/lexical-html/src/import/types.ts:42

Experimental

---

DOMImportConfig

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:36

Experimental

Configuration for DOMImportExtension.

Properties

contextDefaults

readonly contextDefaults: readonly ImportContextPairOrUpdater[]

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:57

Experimental

Default context pairs applied to every $generateNodesFromDOM call. Per-call overrides can be supplied via GenerateNodesFromDOMOptions.context.

preprocess

readonly preprocess: readonly DOMPreprocessFn[]

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:70

Experimental

Functions run in order on the DOM before walking begins, mutating in place. The default config registers $inlineStylesFromStyleSheets (resolves <style> rules to inline styles so the rules' style-driven matchers see them); apps append additional preprocessors (e.g. strip unsafe elements, normalize attributes, resolve relative URLs).

mergeConfig appends, so each contributing extension's preprocessors run in dependency order. Per-call preprocessors registered via GenerateNodesFromDOMOptions.preprocess run AFTER these.

rules

readonly rules: readonly DOMImportRuleEntry[]

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:51

Experimental

The set of rules contributed by this extension and its dependencies. Entries can be raw DOMImportRules or a CompiledOverlayRules produced by defineOverlayRules (the latter is inlined in priority order — useful for libraries that already publish a compiled overlay).

Rules are dispatched in priority order: rules contributed by extensions merged later (i.e. closer to the editor root) run first and may call $next() to delegate to lower-priority rules.

mergeConfig prepends partial.rules to existing rules, so later configuration carries higher priority.

---

DOMImportContext

Defined in: packages/lexical-html/src/import/types.ts:190

Experimental

Context exposed to a rule's $import function. Mirrors the existing render context (see RenderContext) but is import-scoped.

Type Parameters

C

C extends Record<string, RegExpMatchArray> = Record<string, never>

Properties

captures

readonly captures: Readonly<C>

Defined in: packages/lexical-html/src/import/types.ts:194

Experimental

Captures from this rule's selector. Fresh per rule invocation.

session

readonly session: ImportSession

Defined in: packages/lexical-html/src/import/types.ts:203

Experimental

Mutable, document-order-shared store. Use to make information from earlier-visited nodes available to later-visited ones (e.g. a <style> or <meta> at the top of the document influencing how later elements are interpreted). One ImportSession instance is created per top-level $generateNodesFromDOM call and is shared across all recursive $importChildren / $importOne invocations.

Methods

$importChildren()

$importChildren(parent, opts?): LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:214

Experimental

Recursively import every child of parent and return the produced lexical nodes, optionally enforcing a ChildSchema and/or branching the import context for the duration of the call (via opts.context).

Parameters

parent

ParentNode

opts?

ImportChildrenOpts

Returns

LexicalNode[]

$importOne()

$importOne(node, opts?): LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:219

Experimental

Recursively import a single DOM node.

Parameters

node

Node

opts?

ImportNodeOpts

Returns

LexicalNode[]

get()

get<V>(cfg): V

Defined in: packages/lexical-html/src/import/types.ts:206

Experimental

Read a typed context value.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

Returns

V

---

DOMImportExtensionOutput

Defined in: packages/lexical-html/src/import/types.ts:456

Experimental

Output of DOMImportExtension.

Methods

$generateNodesFromDOM()

$generateNodesFromDOM(dom, options?): LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:465

Experimental

Convert a Document or ParentNode into lexical nodes, using the dispatcher compiled from this extension's configured DOMImportRules.

Must be called within an editor.update() or editor.read() because the importers may invoke $create... helpers.

Parameters

dom

Document | ParentNode

options?

GenerateNodesFromDOMOptions

Returns

LexicalNode[]

---

DOMImportRule

Defined in: packages/lexical-html/src/import/types.ts:365

Experimental

An importer for a DOM node, dispatched by match and implemented by $import.

Type Parameters

S

S extends CompiledSelector = CompiledSelector

Properties

$import

readonly $import: DOMImportFn<NodeOfSelector<S>, CapturesOfSelector<S>>

Defined in: packages/lexical-html/src/import/types.ts:375

Experimental

Middleware that converts the matched DOM node into lexical nodes.

match

readonly match: S

Defined in: packages/lexical-html/src/import/types.ts:373

Experimental

A CompiledSelector produced by the sel builder.

name?

readonly optional name?: string

Defined in: packages/lexical-html/src/import/types.ts:371

Experimental

Optional identifier surfaced in dev-mode logs, error messages, and introspection devtools. Convention: '@scope/package/rule-id' for library rules.

---

DOMOverrideOptions

Defined in: packages/lexical-html/src/types.ts:149

Experimental

Options for domOverride controlling whether an override is installed, based only on render context. Both predicates default to "not disabled".

Properties

disabledForEditor?

optional disabledForEditor?: (ctx) => boolean

Defined in: packages/lexical-html/src/types.ts:157

Experimental

Gate residency in the editor's render config (used by reconciliation and as the base for export/generate). Evaluated against the persistent editor context at compile time, and re-evaluated when that context changes via $setRenderContextValue; a change recompiles the config and re-renders affected nodes. Return true to remove the override. Default: not disabled.

Parameters

ctx

RenderContextReader

Returns

boolean

disabledForSession?

optional disabledForSession?: (ctx) => boolean

Defined in: packages/lexical-html/src/types.ts:164

Experimental

Gate participation in a single export/generate session. Evaluated once at the start of each session against that session's context. Has no effect on live reconciliation (which is not a session). Return true to remove the override for that session. Default: not disabled.

Parameters

ctx

RenderContextReader

Returns

boolean

---

DOMPreprocessContext

Defined in: packages/lexical-html/src/import/types.ts:392

Experimental

Context exposed to a DOMPreprocessFn. Lets the preprocessor:

• Write to the per-import ImportSession (the same ctx.session rules see during the walk). Writes mutate the root-layer context record, so they are visible to every scoped ctx.get(cfg) read that hasn't been shadowed by a branch.

Properties

session

readonly session: ImportSession

Defined in: packages/lexical-html/src/import/types.ts:399

Experimental

Document-order-shared store, same instance as ctx.session in rules. Use to pass info from the DOM preprocess phase (e.g. inspected <meta> tags, collected <style> text) to the importer rules.

---

DOMRenderConfig

Defined in: packages/lexical-html/src/types.ts:199

Experimental

Configuration for DOMRenderExtension

Properties

contextDefaults

contextDefaults: AnyRenderStateConfigPairOrUpdater[]

Defined in: packages/lexical-html/src/types.ts:220

Experimental

Default context to provide in all exports, the configurations are created with createRenderState and should be created at the module-level.

Only specify these if overriding the default value globally, since each configuration has a built-in default value that will be used if not already present in the context.

overrides

overrides: AnyDOMRenderMatch[]

Defined in: packages/lexical-html/src/types.ts:211

Experimental

DOMRenderMatch overrides to customize node behavior, the final priority of these will be based on the following criteria:

• Wildcards ('*') have highest priority
• Predicates ($isParagraphNode) have next priority
• Subclasses have higher priority (e.g. ParagraphNode before ElementNode)
• Extensions closer to the root have higher priority
• Extensions depended on later have higher priority
• Overrides defined later have higher priority

---

DOMRenderExtensionOutput

Defined in: packages/lexical-html/src/types.ts:92

Experimental

---

DOMRenderMatch

Defined in: packages/lexical-html/src/types.ts:257

Experimental

Used to define overrides for the render and export behavior for nodes matching the nodes predicate.

All of these overrides are in a middleware style where you may use the result of $next() to enhance the result of the default implementation (or a lower priority override) by calling it and manipulating the result, or you may choose not to call $next() to entirely replace the behavior.

It is not permitted to update the lexical editor state during any of these calls, you should only be doing read-only operations.

Type Parameters

T

T extends LexicalNode

Properties

$createDOM?

optional $createDOM?: (node, $next, editor) => HTMLElement

Defined in: packages/lexical-html/src/types.ts:304

Experimental

Called during the reconciliation process to determine which nodes to insert into the DOM for this Lexical Node. This is also the default implementation of $exportDOM for most nodes.

This method must return exactly one HTMLElement.

Nested elements are not supported except with DecoratorNode (which have unmanaged contents) or ElementNode using an appropriate $getDOMSlot return value.

Parameters

node

T

The LexicalNode

$next

() => HTMLElement

Call the next implementation

editor

LexicalEditor

The editor

Returns

HTMLElement

The HTMLElement for this node to be rendered in the editor

$decorateDOM?

optional $decorateDOM?: (nextNode, prevNode, dom, editor) => void

Defined in: packages/lexical-html/src/types.ts:355

Experimental

Called after a node is created or updated and should make any in-place updates to the DOM in whatever way is necessary to make it align with any changes that might have happened during the $createDOM or $updateDOM. This also runs after any children have been reconciled.

Use this when you have code that you would need to duplicate in both methods, or if there is a need to ensure that the children are also reconciled before performing this in-place update.

Unlike other overrides, all applicable $decorateDOM functions are called unconditionally. There is no $next argument, because there are no known use cases for avoiding the next implementation and due to the void return value it would be error-prone and add boilerplate to require calling it.

The ordering here is equivalent to an implicit $next call first.

Parameters

nextNode

T

The current version of this node

prevNode

T | null

The previous version of this node if $updateDOM returned false, or null if $createDOM was just called

dom

HTMLElement

The previously rendered HTMLElement for this node

editor

LexicalEditor

The editor

Returns

void

$exportDOM?

optional $exportDOM?: (node, $next, editor) => DOMExportOutput

Defined in: packages/lexical-html/src/types.ts:374

Experimental

Controls how the this node is serialized to HTML. This is important for copy and paste between Lexical and non-Lexical editors, or Lexical editors with different namespaces, in which case the primary transfer format is HTML. It's also important if you're serializing to HTML for any other reason via $generateHtmlFromNodes.

Parameters

node

T

The LexicalNode

$next

() => DOMExportOutput

Call the next implementation

editor

LexicalEditor

The editor

Returns

DOMExportOutput

A DOMExportOutput structure that defines how the node should be exported to HTML

$extractWithChild?

optional $extractWithChild?: (node, childNode, selection, destination, $next, editor) => boolean

Defined in: packages/lexical-html/src/types.ts:440

Experimental

Return true if this node should be included in the export based on childNode, even if it would not otherwise be included based on its $shouldInclude result.

Typically used to ensure that required wrapping nodes are always present with its children, e.g. a ListNode when some of its ListItemNode children are selected.

This has higher precedence than $extractWithChild and lower precedence than $shouldExclude.

Parameters

node

T

The lexical node

childNode

LexicalNode

A child of this lexical node

selection

BaseSelection | null

The current selection

destination

"clone" | "html"

Currently always 'html'

$next

() => boolean

The next implementation

editor

LexicalEditor

The editor

Returns

boolean

true if this

$getDOMSlot?

optional $getDOMSlot?: (node, dom, $next, editor) => DOMSlotForNode<T>

Defined in: packages/lexical-html/src/types.ts:282

Experimental

Control where an ElementNode's children are inserted into the DOM, this is useful to add a wrapping node or accessory nodes before or after the children. The root of the node returned by createDOM must still be exactly one HTMLElement.

Generally you will call $next() to get a slot and then use its methods to create a new one. The slot type is narrowed via DOMSlotForNode: for ElementNode it resolves to ElementDOMSlot with children-management semantics; for non-Element nodes the base DOMSlot pointing at the keyed DOM.

Parameters

node

T

The LexicalNode

dom

HTMLElement

The rendered HTMLElement

$next

() => DOMSlotForNode<T>

Call the next implementation

editor

LexicalEditor

The editor

Returns

DOMSlotForNode<T>

The slot for this node

$shouldExclude?

optional $shouldExclude?: (node, selection, $next, editor) => boolean

Defined in: packages/lexical-html/src/types.ts:392

Experimental

Equivalent to ElementNode.excludeFromCopy, if it returns true this lexical node will not be exported to DOM (but if it's an ElementNode its children may still be inserted in its place).

Has higher precedence than $shouldInclude and $extractWithChild.

Parameters

node

T

The LexicalNode

selection

BaseSelection | null

The current selection

$next

() => boolean

The next implementation

editor

LexicalEditor

The editor

Returns

boolean

true to exclude this node, false otherwise

$shouldInclude?

optional $shouldInclude?: (node, selection, $next, editor) => boolean

Defined in: packages/lexical-html/src/types.ts:414

Experimental

Return true if this node should be included in the export, typically based on the current selection (all nodes by default are included when there is no selection).

The default implementation is equivalent to selection ? node.isSelected(selection) : true.

This has lower precedence than $extractWithChild and $shouldExclude.

Parameters

node

T

The current node

selection

BaseSelection | null

The current selection

$next

() => boolean

The next implementation

editor

LexicalEditor

The editor

Returns

boolean

true if this node should be included in the export, false otherwise

$updateDOM?

optional $updateDOM?: (nextNode, prevNode, dom, $next, editor) => boolean

Defined in: packages/lexical-html/src/types.ts:325

Experimental

Called when a node changes and should update the DOM in whatever way is necessary to make it align with any changes that might have happened during the update.

Returning true here will cause lexical to unmount and recreate the DOM node (by calling $createDOM). You would need to do this if the element tag changes, for instance.

Parameters

nextNode

T

The current version of this node

prevNode

T

The previous version of this node

dom

HTMLElement

The previously rendered HTMLElement for this node

$next

() => boolean

Call the next implementation

editor

LexicalEditor

The editor

Returns

boolean

false if no update needed or was performed in-place, true if $createDOM should be called to re-create the node

disabledForEditor?

optional disabledForEditor?: (ctx) => boolean

Defined in: packages/lexical-html/src/types.ts:452

Experimental

Set via domOverride's options argument, not directly. See DOMOverrideOptions.disabledForEditor.

Parameters

ctx

RenderContextReader

Returns

boolean

disabledForSession?

optional disabledForSession?: (ctx) => boolean

Defined in: packages/lexical-html/src/types.ts:457

Experimental

Set via domOverride's options argument, not directly. See DOMOverrideOptions.disabledForSession.

Parameters

ctx

RenderContextReader

Returns

boolean

nodes

readonly nodes: "*" | readonly NodeMatch<T>[]

Defined in: packages/lexical-html/src/types.ts:263

Experimental

'*' for all nodes, or an array of NodeClass | $isNodeGuard to match nodes more specifically. Using classes is more efficient, but will also target subclasses.

---

ElementSelectorBuilder

Defined in: packages/lexical-html/src/import/types.ts:100

Experimental

Fluent builder for an element selector. The two type parameters carry the matched element type and the named-capture map; each call refines them.

The builder itself implements CompiledSelector so it can be used directly as the match field of a rule — no .build() call needed.

Extends

• CompiledSelector<E, C>

Type Parameters

E

E extends HTMLElement

C

C extends Record<string, RegExpMatchArray> = Record<string, never>

Properties

[CaptureBrand]?

readonly optional [CaptureBrand]?: C

Defined in: packages/lexical-html/src/import/types.ts:43

Experimental

Inherited from

CompiledSelector.[CaptureBrand]

[NodeBrand]?

readonly optional [NodeBrand]?: E

Defined in: packages/lexical-html/src/import/types.ts:42

Experimental

Inherited from

CompiledSelector.[NodeBrand]

Methods

attr()

Call Signature

attr(name, value): ElementSelectorBuilder<E, C>

Defined in: packages/lexical-html/src/import/types.ts:109

Experimental

Require the attribute to be present (any value).

Parameters

name

string

value

true

Returns

ElementSelectorBuilder<E, C>

Call Signature

attr(name, value): ElementSelectorBuilder<E, C>

Defined in: packages/lexical-html/src/import/types.ts:111

Experimental

Require the attribute to equal the given string.

Parameters

name

string

value

string

Returns

ElementSelectorBuilder<E, C>

Call Signature

attr<O>(name, value, options?): ElementSelectorBuilder<E, O extends object ? C & Record<K & string, RegExpMatchArray> : C>

Defined in: packages/lexical-html/src/import/types.ts:117

Experimental

Require the attribute to match the given regex. With {capture: 'name'} the match result is exposed on ctx.captures.name.

Type Parameters

O

O extends AttrMatchOptions<string>

Parameters

name

string

value

RegExp

options?

O

Returns

ElementSelectorBuilder<E, O extends object ? C & Record<K & string, RegExpMatchArray> : C>

classAll()

classAll(...classes): ElementSelectorBuilder<E, C>

Defined in: packages/lexical-html/src/import/types.ts:105

Experimental

Require every listed class to be present on the element.

Parameters

classes

...readonly string[]

Returns

ElementSelectorBuilder<E, C>

classAny()

classAny(...classes): ElementSelectorBuilder<E, C>

Defined in: packages/lexical-html/src/import/types.ts:107

Experimental

Require at least one of the listed classes to be present.

Parameters

classes

...readonly string[]

Returns

ElementSelectorBuilder<E, C>

styleAny()

Call Signature

styleAny(prop, value): ElementSelectorBuilder<E, C>

Defined in: packages/lexical-html/src/import/types.ts:126

Experimental

Require the inline-style declaration to equal value.

Parameters

prop

string

value

string

Returns

ElementSelectorBuilder<E, C>

Call Signature

styleAny<O>(prop, value, options?): ElementSelectorBuilder<E, O extends object ? C & Record<K & string, RegExpMatchArray> : C>

Defined in: packages/lexical-html/src/import/types.ts:128

Experimental

Require the inline-style declaration to match value.

Type Parameters

O

O extends StyleMatchOptions<string>

Parameters

prop

string

value

RegExp

options?

O

Returns

ElementSelectorBuilder<E, O extends object ? C & Record<K & string, RegExpMatchArray> : C>

---

GenerateNodesFromDOMOptions

Defined in: packages/lexical-html/src/import/types.ts:437

Experimental

Per-call options to the extension's $generateNodesFromDOM.

Properties

context?

readonly optional context?: readonly ImportContextPairOrUpdater[]

Defined in: packages/lexical-html/src/import/types.ts:442

Experimental

Context pairs/updaters applied for the duration of this import only — use to communicate per-call info such as the ImportSource.

preprocess?

readonly optional preprocess?: readonly DOMPreprocessFn[]

Defined in: packages/lexical-html/src/import/types.ts:448

Experimental

Additional preprocessors to run on this call only, on top of the extension's configured DOMImportConfig.preprocess. Per-call preprocessors run AFTER the configured ones.

---

ImportChildrenOpts

Defined in: packages/lexical-html/src/import/types.ts:230

Experimental

Options accepted by DOMImportContext.$importChildren. The combination of schema, $onChild, and $after is sufficient to express every child-handling pattern in the legacy forChild / after / wrap-continuous machinery.

Properties

$after?

readonly optional $after?: (children) => LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:248

Experimental

Called once with the full child array after all DOM children have been recursively imported but before ChildSchema.$packageRun is applied. Equivalent to the old after hook.

Parameters

children

LexicalNode[]

Returns

LexicalNode[]

$onChild?

readonly optional $onChild?: (child) => LexicalNode | null | undefined

Defined in: packages/lexical-html/src/import/types.ts:242

Experimental

Called for each produced lexical child immediately after its rule returned, with the chance to substitute or drop it. Equivalent to the old forChild hook but scoped to one $importChildren call.

Parameters

child

LexicalNode

Returns

LexicalNode | null | undefined

context?

readonly optional context?: readonly ImportContextPairOrUpdater[]

Defined in: packages/lexical-html/src/import/types.ts:250

Experimental

Context overrides scoped to the children traversal.

rules?

readonly optional rules?: CompiledOverlayRules

Defined in: packages/lexical-html/src/import/types.ts:268

Experimental

Additional DOMImportRules active only for this children traversal (and any nested $importChildren calls that don't push their own overlay). The overlay is checked BEFORE the main dispatcher, so its rules take precedence; calling $next() from an overlay rule falls through to the next overlay-or-main rule.

Use this to scope cost-bearing rules to where they apply. For example, a GitHub code-table rule installs an overlay that unwraps <tr> / <td> inside the table, without paying that predicate cost on every other <tr> / <td> paste.

The value must be produced by defineOverlayRules; this forces the dispatcher to be compiled once at module scope and reused across $importChildren calls, instead of being recompiled per invocation.

schema?

readonly optional schema?: ChildSchema

Defined in: packages/lexical-html/src/import/types.ts:236

Experimental

How to validate and (re)package produced children. Defaults to whichever schema the parent's importer passed; the top-level entry uses BlockSchema.

---

ImportNodeOpts

Defined in: packages/lexical-html/src/import/types.ts:272

Experimental

Properties

context?

readonly optional context?: readonly ImportContextPairOrUpdater[]

Defined in: packages/lexical-html/src/import/types.ts:273

Experimental

---

ImportSession

Defined in: packages/lexical-html/src/import/types.ts:173

Experimental

A mutable, document-order-shared store for the import pipeline. Lets a rule visited early in the document write information that rules visited later can read — e.g. parse <style> or <meta> and influence subsequent matching.

Implemented as the root-layer ContextRecord of the import walk: ctx.session.set(cfg, v) mutates the slot on that root record, and every unshadowed ctx.get(cfg) read in any branch picks it up. A $importChildren({context: [...]}) branch that explicitly writes the same slot shadows the session value for the duration of that branch.

Methods

get()

get<V>(cfg): V

Defined in: packages/lexical-html/src/import/types.ts:175

Experimental

Read the current value, returning the config's default if unset.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

Returns

V

has()

has<V>(cfg): boolean

Defined in: packages/lexical-html/src/import/types.ts:181

Experimental

Returns true if the slot has been written since session creation.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

Returns

boolean

set()

set<V>(cfg, value): void

Defined in: packages/lexical-html/src/import/types.ts:177

Experimental

Write value into the slot.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

value

V

Returns

void

update()

update<V>(cfg, updater): void

Defined in: packages/lexical-html/src/import/types.ts:179

Experimental

Read-modify-write.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

updater

(prev) => V

Returns

void

---

RenderContextReader

Defined in: packages/lexical-html/src/types.ts:106

Experimental

A read-only view of a render context layer, passed to the DOMOverrideOptions predicates so they can decide whether an override should be installed based only on context values.

Methods

get()

get<V>(cfg): V

Defined in: packages/lexical-html/src/types.ts:107

Experimental

Type Parameters

V

V

Parameters

cfg

RenderStateConfig<V>

Returns

V

---

StyleMatchOptions

Defined in: packages/lexical-html/src/import/types.ts:87

Experimental

Options bag for ElementSelectorBuilder.styleAny when the value is a regex. See AttrMatchOptions for capture semantics.

Type Parameters

K

K extends string = string

Properties

capture?

readonly optional capture?: K

Defined in: packages/lexical-html/src/import/types.ts:88

Experimental

---

WhitespaceImportConfig

Defined in: packages/lexical-html/src/import/ImportContext.ts:184

Experimental

Configuration for the core text whitespace-collapse logic. Override via ImportWhitespaceConfig either as a contextDefaults entry on the DOMImportExtension or per-call on $generateNodesFromDOM's context option.

Properties

isInline

readonly isInline: IsInlineForWhitespace

Defined in: packages/lexical-html/src/import/ImportContext.ts:188

Experimental

See IsInlineForWhitespace.

preservesWhitespace

readonly preservesWhitespace: IsPreserveWhitespaceDom

Defined in: packages/lexical-html/src/import/ImportContext.ts:186

Experimental

See IsPreserveWhitespaceDom.

Type Aliases

AnyDOMImportRule

AnyDOMImportRule = DOMImportRule<any>

Defined in: packages/lexical-html/src/import/types.ts:380

Experimental

---

AnyDOMRenderMatch

AnyDOMRenderMatch = DOMRenderMatch<any>

Defined in: packages/lexical-html/src/types.ts:228

Experimental

Any DOMRenderMatch

---

AnyRenderStateConfig

AnyRenderStateConfig = RenderStateConfig<any>

Defined in: packages/lexical-html/src/types.ts:192

Experimental

Any RenderStateConfig

---

AnyRenderStateConfigPairOrUpdater

AnyRenderStateConfigPairOrUpdater = AnyContextConfigPairOrUpdater<typeof DOMRenderContextSymbol>

Defined in: packages/lexical-html/src/types.ts:182

Experimental

Any setter or updater for RenderStateConfig

---

CapturesOfSelector

CapturesOfSelector<S> = S extends CompiledSelector<Node, infer C> ? C : Record<string, never>

Defined in: packages/lexical-html/src/import/types.ts:62

Experimental

The named-capture map for a selector.

Type Parameters

S

S

---

ContextPairOrUpdater

ContextPairOrUpdater<Ctx, V> = ContextConfigPair<Ctx, V> | ContextConfigUpdater<Ctx, V>

Defined in: packages/lexical-html/src/types.ts:82

Experimental

Set or update a context value, constructed with contextValue or contextUpdater

Type Parameters

Ctx

Ctx extends AnyContextSymbol

V

V

---

DOMImportFn

DOMImportFn<E, C> = (ctx, node, $next) => readonly LexicalNode[]

Defined in: packages/lexical-html/src/import/types.ts:350

Experimental

The middleware signature of an import rule. Call $next() to delegate to the next-matching rule for this node (returning its result, which may then be inspected or wrapped); return [] to drop the node.

Type Parameters

E

E extends Node

C

C extends Record<string, RegExpMatchArray> = Record<string, never>

Parameters

ctx

DOMImportContext<C>

node

E

$next

() => readonly LexicalNode[]

Returns

readonly LexicalNode[]

---

DOMImportRuleEntry

DOMImportRuleEntry = AnyDOMImportRule | CompiledOverlayRules

Defined in: packages/lexical-html/src/import/defineOverlayRules.ts:49

Experimental

An entry accepted everywhere rules are configured (overlay definitions, DOMImportConfig.rules). Either a single DOMImportRule or a CompiledOverlayRules produced by a previous defineOverlayRules call — passing the latter inlines the overlay's rules at this position in priority order.

---

DOMPreprocessFn

DOMPreprocessFn = (dom, ctx, $next) => void

Defined in: packages/lexical-html/src/import/types.ts:426

Experimental

A middleware step in the DOM-preprocess chain. Runs before walking begins and may:

• Mutate the input DOM in place (e.g. inline stylesheets, strip unsafe elements, normalize attributes).
• Write to DOMPreprocessContext.session for rules to read (and for unshadowed scoped reads to pick up).
• Call $next() to defer to the next-lower preprocessor in the stack; omit the call to short-circuit and skip the rest.

The preprocess phase runs inside the same editor read / update context as the walk that follows, so a preprocess function may call $-prefixed Lexical APIs (e.g. $getState, $getRoot) as needed. The $next parameter is named with a $ prefix to make that editor-context expectation visible to readers and lints.

Append-style merge applies: an extension's preprocessors are appended to the existing stack, so later-registered preprocessors run first and may delegate to earlier (lower-priority) ones via $next(). Same convention as ExportMimeTypeFunction on the export side.

Parameters

dom

Document | ParentNode

ctx

DOMPreprocessContext

$next

() => void

Returns

void

---

DOMRenderMatchConfig

DOMRenderMatchConfig<T> = Omit<DOMRenderMatch<T>, "nodes" | keyof DOMOverrideOptions>

Defined in: packages/lexical-html/src/types.ts:467

Experimental

The hook fields of a DOMRenderMatch — i.e. without nodes or the DOMOverrideOptions predicates, which are passed separately to domOverride.

Type Parameters

T

T extends LexicalNode

---

ImportContextPairOrUpdater

ImportContextPairOrUpdater = AnyContextConfigPairOrUpdater<typeof DOMImportContextSymbol>

Defined in: packages/lexical-html/src/import/types.ts:144

Experimental

Argument to DOMImportContext.branch / $importChildren({context}) — see ContextConfigPair / ContextConfigUpdater.

---

ImportSourceKind

ImportSourceKind = "paste" | "unknown"

Defined in: packages/lexical-html/src/import/ImportContext.ts:76

Experimental

The kind of operation that produced this import. Lets rules adapt their behavior (e.g. preserve more whitespace on 'paste'). Defaults to 'unknown'. Apps that need a different vocabulary can define their own ImportStateConfig with whatever value type they want.

---

ImportStateConfig

ImportStateConfig<V> = ContextConfig<typeof DOMImportContextSymbol, V>

Defined in: packages/lexical-html/src/import/types.ts:154

Experimental

A typed context-state key for the import pipeline. Create with createImportState.

Type Parameters

V

V

---

IsInlineForWhitespace

IsInlineForWhitespace = (node) => boolean

Defined in: packages/lexical-html/src/import/ImportContext.ts:174

Experimental

Determines whether a given DOM node sits on the same visual line as its adjacent text siblings, governing whether leading/trailing whitespace in a #text is collapsed against neighbors. The default consults isInlineDomNode from lexical (style.display or a fixed inline tag-name set) and additionally treats elements with an explicit non-inline display style as block.

Parameters

node

Node

Returns

boolean

---

IsPreserveWhitespaceDom

IsPreserveWhitespaceDom = (node) => boolean

Defined in: packages/lexical-html/src/import/ImportContext.ts:162

Experimental

Determines whether a given DOM element should be treated as preserving whitespace (i.e. text content under it is not collapsed and is split on \n / \t into LineBreakNode / TabNode). The default matches the legacy behavior: the element itself is <pre> or its inline white-space style begins with 'pre'.

Parameters

node

Node

Returns

boolean

---

NodeMatch

NodeMatch<T> = Klass<T> | ((node) => node is T)

Defined in: packages/lexical-html/src/types.ts:239

Experimental

Match a node (and any subclass of that node) by its LexicalNode class, or with a guard (e.g. ElementNode or $isElementNode).

Note that using the class compiles to significantly more efficient code than using a guard.

Type Parameters

T

T extends LexicalNode

---

NodeOfSelector

NodeOfSelector<S> = S extends CompiledSelector<infer N, Record<string, RegExpMatchArray>> ? N : Node

Defined in: packages/lexical-html/src/import/types.ts:52

Experimental

The Node subtype matched by a selector (e.g. HTMLAnchorElement for sel.tag('a'), Text for sel.text()).

Type Parameters

S

S

Variables

$inlineStylesFromStyleSheets

const $inlineStylesFromStyleSheets: DOMPreprocessFn

Defined in: packages/lexical-html/src/import/inlineStylesFromStyleSheets.ts:31

Experimental

Inlines CSS rules from <style> tags onto matching elements as inline styles.

Used by apps like Excel that generate HTML where styles live in class-based <style> rules (e.g. .xl65 { background: #FFFF00; color: blue; }) rather than inline styles. Since Lexical's import converters read inline styles, we resolve stylesheet rules into inline styles before conversion.

Mutates the DOM in-place. Original inline styles always take precedence over stylesheet rules (matching CSS specificity behavior).

No-op for ParentNodes that are not Documents — only a full document carries styleSheets we can iterate.

---

$withImportContext

const $withImportContext: (cfg, editor?) => <T>(f) => T

Defined in: packages/lexical-html/src/import/ImportContext.ts:333

Experimental

Run f with the given context pairs applied on top of the editor's current import context.

Parameters

cfg

readonly ImportContextPairOrUpdater[]

editor?

LexicalEditor

Returns

<T>(f) => T

---

$withRenderContext

const $withRenderContext: (cfg, editor?) => <T>(f) => T

Defined in: packages/lexical-html/src/RenderContext.ts:162

Experimental

Execute a callback within a render context with the given config pairs.

Parameters

cfg

readonly AnyRenderStateConfigPairOrUpdater[]

editor?

LexicalEditor

Returns

<T>(f) => T

---

BlockSchema

const BlockSchema: ChildSchema

Defined in: packages/lexical-html/src/import/schemas.ts:183

Experimental

Default schema for block-level positions (root of the document, the body of a block element node). Accepts block lexical nodes; packages runs of inline children into fresh paragraph nodes.

---

CoreImportExtension

const CoreImportExtension: LexicalExtension<ExtensionConfigBase, "@lexical/html/CoreImport", unknown, unknown>

Defined in: packages/lexical-html/src/import/CoreImportExtension.ts:23

Experimental

Bundles CoreImportRules into a DOMImportExtension-aware extension. Depend on this from your editor (directly or via richer extensions like RichTextImportExtension) to get the equivalent of the legacy core importDOM behavior for <p>, <span>, <b>, <strong>, <em>, <i>, <code>, <mark>, <s>, <sub>, <sup>, <u>, <br>, and #text.

---

CoreImportRules

const CoreImportRules: (DOMImportRule<CompiledSelector<Text, Record<string, RegExpMatchArray>>> | DOMImportRule<ElementSelectorBuilder<HTMLElement | HTMLSpanElement, Record<string, never>>>)[]

Defined in: packages/lexical-html/src/import/coreImportRules.ts:479

Experimental

Rules covering the ParagraphNode, TextNode, LineBreakNode, and TabNode cases that the legacy importDOM machinery in @lexical/lexical handled. Intended to be registered as a dependency of every editor that uses DOMImportExtension.

---

DOMImportExtension

const DOMImportExtension: LexicalExtension<DOMImportConfig, "@lexical/html/DOMImport", DOMImportExtensionOutput, void>

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:123

Experimental

Extension-based replacement for the legacy importDOM / DOMConversion machinery. Rules are contributed via configuration (see DOMImportConfig.rules), compiled into a tag-bucketed dispatcher at editor build time, and consumed via the extension's DOMImportExtensionOutput.$generateNodesFromDOM output.

The legacy $generateNodesFromDOM continues to work in parallel; the intent is to migrate node packages over to this extension incrementally.

---

DOMRenderExtension

const DOMRenderExtension: LexicalExtension<DOMRenderConfig, "@lexical/html/DOM", DOMRenderExtensionOutput, DOMRenderInitResult>

Defined in: packages/lexical-html/src/DOMRenderExtension.ts:38

Experimental

An extension that allows overriding the render and export behavior for an editor. This is highly experimental and subject to change from one version to the next.

---

HorizontalRuleImportExtension

const HorizontalRuleImportExtension: LexicalExtension<ExtensionConfigBase, "@lexical/html/HorizontalRuleImport", unknown, unknown>

Defined in: packages/lexical-html/src/import/HorizontalRuleImportExtension.ts:46

Experimental

Bundles HorizontalRuleImportRules (plus CoreImportExtension) into a single dependency. The legacy HorizontalRuleExtension.importDOM continues to work in parallel; depend on this extension to opt into the new pipeline.

Lives in @lexical/html (not @lexical/extension) because DOMImportExtension itself is in @lexical/html, and @lexical/extension is upstream of @lexical/html in the dependency graph — same arrangement as CoreImportExtension.

---

HorizontalRuleImportRules

const HorizontalRuleImportRules: DOMImportRule<ElementSelectorBuilder<HTMLHRElement, Record<string, never>>>[]

Defined in: packages/lexical-html/src/import/HorizontalRuleImportExtension.ts:31

Experimental

Import rules for HorizontalRuleNode.

---

ImportOverlays

const ImportOverlays: ImportStateConfig<readonly CompiledOverlayRules[]>

Defined in: packages/lexical-html/src/import/ImportContext.ts:265

Experimental

Built-in session slot for runtime overlay rules that should be in effect for the entire walk. A preprocessor writes here when it wants to conditionally install handling for a particular paste source (e.g. "if the Microsoft Word generator meta tag is present, push the Word-paste overlay"). Each entry contributes an overlay dispatcher to the runtime's overlay stack; later array entries are higher priority. Use ctx.session.update(ImportOverlays, prev => […]) to append.

This is the walk-wide counterpart to $importChildren({rules: …}) (which scopes an overlay to one subtree): write to ImportOverlays when the overlay should apply for the whole document; use $importChildren's rules when the overlay should only apply for a deeper region.

---

ImportSource

const ImportSource: ImportStateConfig<ImportSourceKind>

Defined in: packages/lexical-html/src/import/ImportContext.ts:84

Experimental

Built-in import-context state identifying how this import was initiated. Callers of $generateNodesFromDOM should set it via the context option.

---

ImportSourceDataTransfer

const ImportSourceDataTransfer: ImportStateConfig<DataTransfer | null>

Defined in: packages/lexical-html/src/import/ImportContext.ts:110

Experimental

Built-in import-context state holding the DataTransfer the import was sourced from, if any. null outside paste/drop flows.

The clipboard import pipeline passes the original DataTransfer through to its per-MIME-type handler stack (see ImportMimeTypeFunction); handlers that route HTML through the DOMImportExtension pipeline should forward it into the walk via context: [contextValue(ImportSourceDataTransfer, dataTransfer)] so rules and preprocessors can call ctx.get(ImportSourceDataTransfer) to inspect companion MIME types (e.g. an 'application/rtf' alternative or an attached 'application/x-officedrawing' payload), the file list, or any custom drag-and-drop slot.

Use sparingly: the safer pattern is to decide which MIME-type payload to walk in the clipboard handler stack and hand a finalized DOM to the rules; only fall back to peeking at ImportSourceDataTransfer when the source-detection signal genuinely lives in a companion slot.

---

ImportTextFormat

const ImportTextFormat: ImportStateConfig<number>

Defined in: packages/lexical-html/src/import/ImportContext.ts:125

Experimental

Built-in import-context state holding the bit-packed TextFormatType formats that should apply to TextNodes produced during the current subtree. Used by inline-format wrappers (<b>, <i>, <u>, …) to propagate formatting through the context record instead of via the legacy forChild chain.

---

ImportTextStyle

const ImportTextStyle: ImportStateConfig<Readonly<Record<string, string>>>

Defined in: packages/lexical-html/src/import/ImportContext.ts:146

Experimental

Built-in import-context state holding a parsed CSS-style record (the getStyleObjectFromCSS shape) that should apply to TextNodes produced during the current subtree. Mirrors the format-bit propagation in ImportTextFormat for properties that don't fit into the format bit mask — color, font-family, font-size, etc.

Ancestor rules that contribute a style branch the context with a merged record; the core #text rule materializes the non-empty record to a CSS string and calls setStyle on the new TextNode. Once TextNode adopts a parsed style record, the materialization step will go away.

---

ImportWhitespaceConfig

const ImportWhitespaceConfig: ImportStateConfig<WhitespaceImportConfig>

Defined in: packages/lexical-html/src/import/ImportContext.ts:241

Experimental

Built-in import-context state controlling text-node whitespace handling (collapse vs. preserve, what counts as an inline sibling). Override per editor via DOMImportConfig.contextDefaults or per call via GenerateNodesFromDOMOptions.context.

---

InlineSchema

const InlineSchema: ChildSchema

Defined in: packages/lexical-html/src/import/schemas.ts:196

Experimental

Schema for inline-only positions (the body of an inline lexical node such as a link). Accepts non-block lexical nodes; runs of block children are dropped (onReject: 'drop' is the default).

---

NestedBlockSchema

const NestedBlockSchema: ChildSchema

Defined in: packages/lexical-html/src/import/schemas.ts:211

Experimental

Schema for nested block positions — the equivalent of the legacy ArtificialNode__DO_NOT_USE flow used when a block DOM element appears inside another block lexical ancestor. Accepts block nodes; runs of inline children are emitted with a line break between consecutive runs (instead of being wrapped in a paragraph, which would introduce an extra level of nesting).

---

RenderContextExport

const RenderContextExport: RenderStateConfig<boolean>

Defined in: packages/lexical-html/src/RenderContext.ts:59

Experimental

Render context state that is true if this is an export operation ($generateHtmlFromNodes).

---

RenderContextRoot

const RenderContextRoot: RenderStateConfig<boolean>

Defined in: packages/lexical-html/src/RenderContext.ts:53

Experimental

Render context state that is true if the export was initiated from the root of the document.

---

RootSchema

const RootSchema: ChildSchema

Defined in: packages/lexical-html/src/import/schemas.ts:232

Experimental

Schema for the topmost level of $generateNodesFromDOM. Identical to BlockSchema; aliased for clarity at the entry point and so it can be overridden separately in the future (e.g. to synthesize a ListNode around runs of orphan ListItemNodes).

---

sel

const sel: object

Defined in: packages/lexical-html/src/import/index.ts:18

Experimental

Combinator-and-parser-based builder for CompiledSelectors. The runtime shape returned by these factory methods is opaque; consumers should never inspect or construct selector objects directly.

Type Declaration

any

readonly any: () => ElementSelectorBuilder<HTMLElement> = selBase.any

Match any HTMLElement.

Returns

ElementSelectorBuilder<HTMLElement>

comment

readonly comment: () => CompiledSelector<Comment> = selBase.comment

Match DOM Comment nodes.

Returns

CompiledSelector<Comment>

css

readonly css: (source) => ElementSelectorBuilder<HTMLElement> = parseSelector

Parse a reduced CSS-selector subset and return a builder you can chain combinator methods off of.

Experimental

Parse a reduced CSS-selector subset and return a CompiledSelector. Supported:

• Tag (p), wildcard (*).
• Tag list (h1, h2, h3).
• Class (.foo, .foo.bar).
• ID (#foo).
• Attribute presence ([name]).
• Attribute equality ([name="value"], [name=value]).

Anything outside the subset (regex attribute, inline-style match, combinators, pseudo-classes) is intentionally rejected — chain combinator methods off the returned builder instead.

Parameters

source

string

Returns

ElementSelectorBuilder<HTMLElement>

tag

readonly tag: <Tags>(...tags) => ElementSelectorBuilder<Tags[number] extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[any[any]] : HTMLElement> = selBase.tag

Match by tag name(s). With one literal tag the element type is narrowed (e.g. 'a' → HTMLAnchorElement); with multiple, it is the union of their HTMLElementTagNameMap entries.

Type Parameters

Tags

Tags extends readonly string[]

Parameters

tags

...Tags

Returns

ElementSelectorBuilder<Tags[number] extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[any[any]] : HTMLElement>

text

readonly text: () => CompiledSelector<Text> = selBase.text

Match DOM Text nodes.

Returns

CompiledSelector<Text>

Functions

$distributeInlineWrapper()

$distributeInlineWrapper(children, $makeWrapper): LexicalNode[]

Defined in: packages/lexical-html/src/import/schemas.ts:64

Experimental

Distribute an inline wrapper (LinkNode, MarkNode, …) across a heterogeneous run of children produced by $importChildren, lifting any block children to the top level while keeping the wrapper around the leaf inline content.

Use from a rule whose DOM source is an inline element that the browser permitted to enclose block elements — the canonical case is <a href="…"><h1>title</h1><div>body</div></a>, which a link rule wants to surface as two block siblings (heading + paragraph), each with its own link wrapping the original inline content. Schemas can't express this because they reason about a parent's children only — they cannot lift the parent out of itself.

For each top-level child:

• Inline children are collected into runs; each run is wrapped in a single fresh wrapper (from $makeWrapper()).
• Block children are descended into: their own children are recursively distributed with $makeWrapper, then re-attached so the block keeps its position at the top level.

The returned list will contain a mix of blocks and wrapped inline runs. The enclosing schema (typically BlockSchema) will then package those inline wrappers into paragraphs as usual.

Parameters

children

readonly LexicalNode[]

$makeWrapper

() => ElementNode

Returns

LexicalNode[]

---

$generateDOMFromNodes()

$generateDOMFromNodes<T>(container, selection?, editor?): T

Defined in: packages/lexical-html/src/index.ts:180

Experimental

Generate DOM nodes from the editor state into the given container element, using the editor's EditorDOMRenderConfig.

Type Parameters

T

T extends HTMLElement | DocumentFragment

Parameters

container

T

selection?

BaseSelection | null

editor?

LexicalEditor = ...

Returns

T

---

$generateDOMFromRoot()

$generateDOMFromRoot<T>(container, root?): T

Defined in: packages/lexical-html/src/index.ts:211

Experimental

Generate DOM nodes from a root node into the given container element, including the root node itself. Uses the editor's EditorDOMRenderConfig.

Type Parameters

T

T extends HTMLElement | DocumentFragment

Parameters

container

T

root?

LexicalNode = ...

Returns

T

---

$generateHtmlFromNodes()

$generateHtmlFromNodes(editor, selection?): string

Defined in: packages/lexical-html/src/index.ts:241

Generate an HTML string from the editor's current state (or selection if provided).

Must be called inside an active editor scope — i.e. editor.update(...), editor.read(...), or editor.getEditorState().read(callback, {editor}). The legacy editor.getEditorState().read(callback) call (without the {editor} option) does not set an active editor and is not supported; editor.read(...) is the drop-in replacement.

Parameters

editor

LexicalEditor

selection?

BaseSelection | null

Returns

string

---

$generateNodesFromDOM()

$generateNodesFromDOM(editor, dom): LexicalNode[]

Defined in: packages/lexical-html/src/index.ts:144

How you parse your html string to get a document is left up to you. In the browser you can use the native DOMParser API to generate a document (see clipboard.ts), but to use in a headless environment you can use JSDom or an equivalent library and pass in the document here.

Parameters

editor

LexicalEditor

dom

Document | ParentNode

Returns

LexicalNode[]

---

$generateNodesFromDOMViaExtension()

$generateNodesFromDOMViaExtension(dom, options?): LexicalNode[]

Defined in: packages/lexical-html/src/import/DOMImportExtension.ts:213

Experimental

Look up the editor's DOMImportExtension and run its $generateNodesFromDOM. Designed as a drop-in replacement for the legacy $generateNodesFromDOM(editor, dom) signature so it can be supplied to ClipboardImportExtension.$generateNodesFromDOM (or any other consumer that wants to route through the extension pipeline).

Throws if the editor was not built with DOMImportExtension as a dependency.

Parameters

dom

Document | ParentNode

options?

GenerateNodesFromDOMOptions

Returns

LexicalNode[]

---

$getImportContextValue()

$getImportContextValue<V>(cfg, editor?): V

Defined in: packages/lexical-html/src/import/ImportContext.ts:320

Experimental

Read an import context value during an import operation.

Type Parameters

V

V

Parameters

cfg

ImportStateConfig<V>

editor?

LexicalEditor = ...

Returns

V

---

$getRenderContextValue()

$getRenderContextValue<V>(cfg, editor?): V

Defined in: packages/lexical-html/src/RenderContext.ts:84

Experimental

Get a render context value during a DOM render or export operation.

Type Parameters

V

V

Parameters

cfg

RenderStateConfig<V>

editor?

LexicalEditor = ...

Returns

V

---

$getSessionDOMRenderConfig()

$getSessionDOMRenderConfig(editor?): EditorDOMRenderConfig

Defined in: packages/lexical-html/src/RenderContext.ts:149

Experimental

Resolve the EditorDOMRenderConfig to use for the current export/generate session, applying any disabledForSession overrides against the active session context. Falls back to the editor's resident config when DOMRenderExtension is not installed.

Parameters

editor?

LexicalEditor = ...

Returns

EditorDOMRenderConfig

---

$isBlockLevel()

$isBlockLevel(node): boolean

Defined in: packages/lexical-html/src/import/schemas.ts:31

Experimental

True if the node fills a block slot at the root or inside another block — covers both ElementNode-style blocks (paragraph, heading, quote) and block-level DecoratorNodes (HorizontalRuleNode, ImageNode-as-block, etc.). Used by BlockSchema, RootSchema, and NestedBlockSchema.

Parameters

node

LexicalNode

Returns

boolean

---

$setRenderContextValue()

$setRenderContextValue<V>(cfg, value, editor?): void

Defined in: packages/lexical-html/src/RenderContext.ts:110

Experimental

Imperatively set a value in the persistent editor render context.

Unlike $withRenderContext (which scopes values to a callback), this persists on the editor. If the change flips any override's disabledForEditor result, the resident render config is recompiled and the affected nodes are re-rendered. No-op if DOMRenderExtension is not installed.

Type Parameters

V

V

Parameters

cfg

RenderStateConfig<V>

value

V

editor?

LexicalEditor = ...

Returns

void

---

$updateRenderContextValue()

$updateRenderContextValue<V>(cfg, updater, editor?): void

Defined in: packages/lexical-html/src/RenderContext.ts:127

Experimental

Imperatively update a value in the persistent editor render context with an updater function. See $setRenderContextValue.

Type Parameters

V

V

Parameters

cfg

RenderStateConfig<V>

updater

(prev) => V

editor?

LexicalEditor = ...

Returns

void

---

contextUpdater()

contextUpdater<Ctx, V>(cfg, updater): ContextConfigUpdater<Ctx, V>

Defined in: packages/lexical-html/src/ContextRecord.ts:170

Experimental

Create a context config updater that transforms a value in the render context.

Type Parameters

Ctx

Ctx extends AnyContextSymbol

V

V

Parameters

cfg

ContextConfig<Ctx, V>

updater

(prev) => V

Returns

ContextConfigUpdater<Ctx, V>

---

contextValue()

contextValue<Ctx, V>(cfg, value): ContextConfigPair<Ctx, V>

Defined in: packages/lexical-html/src/ContextRecord.ts:159

Experimental

Create a context config pair that sets a value in the render context.

Type Parameters

Ctx

Ctx extends AnyContextSymbol

V

V

Parameters

cfg

ContextConfig<Ctx, V>

value

V

Returns

ContextConfigPair<Ctx, V>

---

createImportState()

createImportState<V>(name, getDefaultValue, isEqual?): ImportStateConfig<V>

Defined in: packages/lexical-html/src/import/ImportContext.ts:54

Experimental

Create an import context state. The phantom symbol prevents accidental use of a render-context state in an import context (and vice versa).

Note: to support the value-or-updater pattern, V cannot be a function type; wrap it in an array or object if needed.

getDefaultValue is called once at state creation and the result is shared between every session that reads the state without first writing a value. Defaults must therefore be immutable (primitives, frozen objects, or read-only arrays / records). If your state needs mutable per-session storage, lazily initialize it inside your rule (e.g. if (!ctx.session.has(cfg)) ctx.session.set(cfg, new …())).

@NO_SIDE_EFFECTS

Type Parameters

V

V

Parameters

name

string

getDefaultValue

() => V

isEqual?

(a, b) => boolean

Returns

ImportStateConfig<V>

---

createRenderState()

createRenderState<V>(name, getDefaultValue, isEqual?): RenderStateConfig<V>

Defined in: packages/lexical-html/src/RenderContext.ts:36

Experimental

Create a context state to be used during render.

Note that to support the ValueOrUpdater pattern you can not use a function for V (but you may wrap it in an array or object).

@NO_SIDE_EFFECTS

Type Parameters

V

V

Parameters

name

string

getDefaultValue

() => V

isEqual?

(a, b) => boolean

Returns

RenderStateConfig<V>

---

defaultIsInline()

defaultIsInline(node): boolean

Defined in: packages/lexical-html/src/import/ImportContext.ts:216

Experimental

Default WhitespaceImportConfig.isInline: treats an element as inline iff its inline display style is inline* OR (no explicit non-inline display) its nodeName is a known inline tag (isInlineDomNode). Text nodes are always inline; comments and other non-elements are not.

Parameters

node

Node

Returns

boolean

---

defaultPreservesWhitespace()

defaultPreservesWhitespace(node): boolean

Defined in: packages/lexical-html/src/import/ImportContext.ts:197

Experimental

Default WhitespaceImportConfig.preservesWhitespace: matches <pre> and any element with white-space: pre*.

Parameters

node

Node

Returns

boolean

---

defineImportRule()

defineImportRule<S>(rule): DOMImportRule<S>

Defined in: packages/lexical-html/src/import/defineImportRule.ts:29

Experimental

Identity helper that infers a rule's matched node type and capture map from its match selector and threads them into the $import signature. Usage:

defineImportRule({
  name: '@lexical/list/li',
  match: sel.tag('li'),
  $import: (ctx, el, $next) => {
    // el: HTMLLIElement
    return [$createListItemNode()];
  },
});

@NO_SIDE_EFFECTS

Type Parameters

S

S extends CompiledSelector<Node, Record<string, RegExpMatchArray>>

Parameters

rule

$import

DOMImportFn<S extends CompiledSelector<N, Record<string, RegExpMatchArray>> ? N : Node, S extends CompiledSelector<Node, C> ? C : Record<string, never>>

match

S

name?

string

Returns

DOMImportRule<S>

---

defineOverlayRules()

defineOverlayRules(entries): CompiledOverlayRules

Defined in: packages/lexical-html/src/import/defineOverlayRules.ts:96

Experimental

Pre-compile a set of DOMImportRuleEntrys into a CompiledOverlayRules handle that can be installed via ctx.$importChildren(el, {rules: …}).

Entries can be raw DOMImportRules or other CompiledOverlayRules (the latter are inlined at their position in priority order, so the same call composes any number of overlays). Earlier entries are higher priority.

Overlay rules installed as a raw array would be re-compiled on every $importChildren call. For overlays that are reused (e.g. a GitHub code-table rule that wraps every matching table), call this once at module scope so the dispatch table is built up front.

Parameters

entries

readonly DOMImportRuleEntry[]

Returns

CompiledOverlayRules

---

domOverride()

Call Signature

domOverride(nodes, config, options?): DOMRenderMatch<LexicalNode>

Defined in: packages/lexical-html/src/domOverride.ts:30

Experimental

A convenience function for type inference when constructing DOM overrides for use with DOMRenderExtension.

The optional options argument controls whether the override is installed based only on render context — disabledForEditor gates residency in the editor's render pipeline (reconciliation), disabledForSession gates participation in a single export/generate session. See DOMOverrideOptions.

@NO_SIDE_EFFECTS

Parameters

nodes

"*"

config

DOMRenderMatchConfig<LexicalNode>

options?

DOMOverrideOptions

Returns

DOMRenderMatch<LexicalNode>

Call Signature

domOverride<T>(nodes, config, options?): DOMRenderMatch<T>

Defined in: packages/lexical-html/src/domOverride.ts:35

Experimental

A convenience function for type inference when constructing DOM overrides for use with DOMRenderExtension.

The optional options argument controls whether the override is installed based only on render context — disabledForEditor gates residency in the editor's render pipeline (reconciliation), disabledForSession gates participation in a single export/generate session. See DOMOverrideOptions.

@NO_SIDE_EFFECTS

Type Parameters

T

T extends LexicalNode

Parameters

nodes

readonly NodeMatch<T>[]

config

DOMRenderMatchConfig<T>

options?

DOMOverrideOptions

Returns

DOMRenderMatch<T>

---

isElementOfTag()

isElementOfTag<T>(node, tag): node is HTMLElementTagNameMap[T]

Defined in: packages/lexical-html/src/import/sel.ts:309

Experimental

Cross-frame-safe replacement for node instanceof HTMLXxxElement. Returns true when node is an HTMLElement whose nodeName equals tag (compared case-insensitively).

Type Parameters

T

T extends keyof HTMLElementTagNameMap

Parameters

node

Node

tag

T

Returns

node is HTMLElementTagNameMap[T]

---

parseSelector()

parseSelector(source): ElementSelectorBuilder<HTMLElement>

Defined in: packages/lexical-html/src/import/parseCss.ts:160

Experimental

Parse a reduced CSS-selector subset and return a CompiledSelector. Supported:

• Tag (p), wildcard (*).
• Tag list (h1, h2, h3).
• Class (.foo, .foo.bar).
• ID (#foo).
• Attribute presence ([name]).
• Attribute equality ([name="value"], [name=value]).

Anything outside the subset (regex attribute, inline-style match, combinators, pseudo-classes) is intentionally rejected — chain combinator methods off the returned builder instead.

Parameters

source

string

Returns

ElementSelectorBuilder<HTMLElement>