@lexical/html
Interfaces
DOMRenderConfig
Defined in: packages/lexical-html/src/types.ts:126
Experimental
Configuration for DOMRenderExtension
Properties
contextDefaults
contextDefaults:
AnyRenderStateConfigPairOrUpdater[]
Defined in: packages/lexical-html/src/types.ts:147
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:138
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.
ParagraphNodebeforeElementNode) - 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:89
Experimental
DOMRenderMatch
Defined in: packages/lexical-html/src/types.ts:184
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:228
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
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:279
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
The editor
Returns
void
$exportDOM?
optional$exportDOM?: (node,$next,editor) =>DOMExportOutput
Defined in: packages/lexical-html/src/types.ts:298
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
The editor
Returns
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:364
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
A child of this lexical node
selection
BaseSelection | null
The current selection
destination
"clone" | "html"
Currently always 'html'
$next
() => boolean
The next implementation
editor
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:206
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
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:316
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
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:338
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
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:249
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
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
readonlynodes:"*"| readonlyNodeMatch<T>[]
Defined in: packages/lexical-html/src/types.ts:190
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.
Type Aliases
AnyDOMRenderMatch
AnyDOMRenderMatch =
DOMRenderMatch<any>
Defined in: packages/lexical-html/src/types.ts:155
Experimental
Any DOMRenderMatch
AnyRenderStateConfig
AnyRenderStateConfig =
RenderStateConfig<any>
Defined in: packages/lexical-html/src/types.ts:119
Experimental
Any RenderStateConfig
AnyRenderStateConfigPairOrUpdater
AnyRenderStateConfigPairOrUpdater =
AnyContextConfigPairOrUpdater<typeofDOMRenderContextSymbol>
Defined in: packages/lexical-html/src/types.ts:109
Experimental
Any setter or updater for RenderStateConfig
ContextPairOrUpdater
ContextPairOrUpdater<
Ctx,V> =ContextConfigPair<Ctx,V> |ContextConfigUpdater<Ctx,V>
Defined in: packages/lexical-html/src/types.ts:79
Experimental
Set or update a context value, constructed with contextValue or contextUpdater
Type Parameters
Ctx
Ctx extends AnyContextSymbol
V
V
NodeMatch
NodeMatch<
T> =Klass<T> | ((node) =>node is T)
Defined in: packages/lexical-html/src/types.ts:166
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
Variables
$withRenderContext
const$withRenderContext: (cfg,editor?) => <T>(f) =>T
Defined in: packages/lexical-html/src/RenderContext.ts:96
Experimental
Execute a callback within a render context with the given config pairs.
Parameters
cfg
readonly AnyRenderStateConfigPairOrUpdater[]
editor?
Returns
<T>(f) => T
DOMRenderExtension
constDOMRenderExtension: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.
RenderContextExport
constRenderContextExport:RenderStateConfig<boolean>
Defined in: packages/lexical-html/src/RenderContext.ts:60
Experimental
Render context state that is true if this is an export operation ($generateHtmlFromNodes).
RenderContextRoot
constRenderContextRoot:RenderStateConfig<boolean>
Defined in: packages/lexical-html/src/RenderContext.ts:54
Experimental
Render context state that is true if the export was initiated from the root of the document.
Functions
$generateDOMFromNodes()
$generateDOMFromNodes<
T>(container,selection?,editor?):T
Defined in: packages/lexical-html/src/index.ts:188
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:219
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:239
Parameters
editor
selection?
BaseSelection | null
Returns
string
$generateNodesFromDOM()
$generateNodesFromDOM(
editor,dom):LexicalNode[]
Defined in: packages/lexical-html/src/index.ts:150
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
dom
Document | ParentNode
Returns
$getRenderContextValue()
$getRenderContextValue<
V>(cfg,editor?):V
Defined in: packages/lexical-html/src/RenderContext.ts:85
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 typeof DOMRenderContextSymbol
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 typeof DOMRenderContextSymbol
V
V
Parameters
cfg
ContextConfig<Ctx, V>
value
V
Returns
ContextConfigPair<Ctx, V>
createRenderState()
createRenderState<
V>(name,getDefaultValue,isEqual?):RenderStateConfig<V>
Defined in: packages/lexical-html/src/RenderContext.ts:37
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>
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
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">