@lexical/html

Interfaces

AttrMatchOptions

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

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

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

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.

Properties

name?

readonly optional name?: string

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

Experimental

Optional name for debug output.

onReject?

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

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

Experimental

Strategy for non-accepted children when packageRun is missing or returns an empty array. 'hoist' lifts them up as siblings of the parent; 'drop' silently removes them.

Methods

accepts()

accepts(child, parent): boolean

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

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

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

Experimental

Package a maximal run of non-accepted siblings into zero or more accepted nodes. If omitted, ChildSchema.onReject is consulted instead.

Parameters

rejected

LexicalNode[]

parent

LexicalNode | null

domParent

Node | null

Returns

LexicalNode[]

---

CompiledSelector

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

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

Experimental

[NodeBrand]?

readonly optional [NodeBrand]?: N

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

Experimental

---

DOMImportConfig

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

Experimental

Configuration for DOMImportExtension.

Properties

contextDefaults

readonly contextDefaults: readonly ImportContextPairOrUpdater[]

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

Experimental

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

rules

readonly rules: readonly AnyDOMImportRule[]

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

Experimental

The set of DOMImportRules contributed by this extension and its dependencies. 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:164

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

Experimental

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

editor

readonly editor: LexicalEditor

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

Experimental

The editor driving this import.

Methods

$importChildren()

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

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

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

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

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

Experimental

Output of DOMImportExtension.

Methods

$generateNodesFromDOM()

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

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

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

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

Experimental

Middleware that converts the matched DOM node into lexical nodes.

match

readonly match: S

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

Experimental

A CompiledSelector produced by the sel builder.

name?

readonly optional name?: string

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

Experimental

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

---

DOMRenderConfig

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

Experimental

Configuration for DOMRenderExtension

Properties

contextDefaults

contextDefaults: AnyRenderStateConfigPairOrUpdater[]

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

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

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

Experimental

---

DOMRenderMatch

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

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

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

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

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

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?: <N>(node, dom, $next, editor) => ElementDOMSlot<HTMLElement>

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

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 an ElementDOMSlot and then use its methods to create a new one.

Type Parameters

N

N extends LexicalNode

Parameters

node

N

The LexicalNode

dom

HTMLElement

The rendered HTMLElement

$next

() => ElementDOMSlot<HTMLElement>

Call the next implementation

editor

LexicalEditor

The editor

Returns

ElementDOMSlot<HTMLElement>

The ElementDOMSlot for this node

$shouldExclude?

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

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

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

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

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

nodes

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

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

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

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

Experimental

Inherited from

CompiledSelector.[CaptureBrand]

[NodeBrand]?

readonly optional [NodeBrand]?: E

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

Experimental

Inherited from

CompiledSelector.[NodeBrand]

Methods

attr()

Call Signature

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

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

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

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

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

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

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

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

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

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

Experimental

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

---

ImportChildrenOpts

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

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

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

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

Experimental

Context overrides scoped to the children traversal.

schema?

readonly optional schema?: ChildSchema

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

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

Experimental

Properties

context?

readonly optional context?: readonly ImportContextPairOrUpdater[]

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

Experimental

---

StyleMatchOptions

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

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

Experimental

Type Aliases

AnyDOMImportRule

AnyDOMImportRule = DOMImportRule<any>

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

Experimental

---

AnyDOMRenderMatch

AnyDOMRenderMatch = DOMRenderMatch<any>

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

Experimental

Any DOMRenderMatch

---

AnyRenderStateConfig

AnyRenderStateConfig = RenderStateConfig<any>

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

Experimental

Any RenderStateConfig

---

AnyRenderStateConfigPairOrUpdater

AnyRenderStateConfigPairOrUpdater = AnyContextConfigPairOrUpdater<typeof DOMRenderContextSymbol>

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

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

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

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

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[]

---

ImportContextPairOrUpdater

ImportContextPairOrUpdater = AnyContextConfigPairOrUpdater<typeof DOMImportContextSymbol>

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

Experimental

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

---

ImportSourceKind

ImportSourceKind = "paste" | "drop" | "deserialize" | "headless" | "unknown"

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

Experimental

The kind of operation that produced this import. Lets rules adapt their behavior (e.g. preserve more whitespace on 'paste', be lenient on 'deserialize', etc.). Defaults to 'unknown'.

---

ImportStateConfig

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

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

Experimental

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

Type Parameters

V

V

---

NodeMatch

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

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

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

Experimental

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

Type Parameters

S

S

Variables

$withImportContext

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

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

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

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

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<HTMLSpanElement, Record<string, never>>>)[]

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

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

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, void>

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

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.

---

ImportSource

const ImportSource: ImportStateConfig<ImportSourceKind>

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

Experimental

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

---

ImportTextFormat

const ImportTextFormat: ImportStateConfig<number>

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

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.

---

InlineSchema

const InlineSchema: ChildSchema

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

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

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

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

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

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

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

Match any HTMLElement.

Returns

ElementSelectorBuilder<HTMLElement>

comment

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

Match DOM Comment nodes.

Returns

CompiledSelector<Comment>

css

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

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

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

Match DOM Text nodes.

Returns

CompiledSelector<Text>

Functions

$generateDOMFromNodes()

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

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

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

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

Parameters

editor

LexicalEditor

selection?

BaseSelection | null

Returns

string

---

$generateNodesFromDOM()

$generateNodesFromDOM(editor, dom): LexicalNode[]

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

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(editor, dom, options?): LexicalNode[]

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

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

editor

LexicalEditor

dom

Document | ParentNode

options?

GenerateNodesFromDOMOptions

Returns

LexicalNode[]

---

$getImportContextValue()

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

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

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

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

---

contextUpdater()

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

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

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

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

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.

@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:34

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>

---

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>

---

domOverride()

Call Signature

domOverride(nodes, config): DOMRenderMatch<LexicalNode>

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

Experimental

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

@NO_SIDE_EFFECTS

Parameters

nodes

"*"

config

Omit<DOMRenderMatch<LexicalNode>, "nodes">

Returns

DOMRenderMatch<LexicalNode>

Call Signature

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

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

Experimental

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

@NO_SIDE_EFFECTS

Type Parameters

T

T extends LexicalNode

Parameters

nodes

readonly NodeMatch<T>[]

config

Omit<DOMRenderMatch<T>, "nodes">

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

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>