[lexical][lexical-html] Feature: Extensible DOM create/update/export

[etrepum]

Description

Addresses the createDOM/updateDOM/exportDOM part of #7259 by parameterizing the DOM functionality from the reconciler and @lexical/html to use the editor config via DOMRenderExtension. Part of the thinking here is that we may be able to leverage this work later to make the reconciler itself more flexible.

(Commit history is noisy because this has been collecting dust and had some failed experiments. I used claude to strip it down to what is actually worth adding soon)

Follow-up work (out of scope)

Does not yet consider the different types of export, e.g. export for clipboard vs. export for serialization.

DOMExportExtension currently only has a natural topological sort of overrides by extension, it should also do another sort to pull wildcard and predicate based matches to the highest precedence and then sort by specificity (topological sort of class inheritance) so that SubclassNode overrides have higher precedence than SuperclassNode overrides.

The same sort of approach can probably also be used for other tree based import/export (json, markdown ast, etc.).

$getDOMSlot could possibly be used for nodes other than just ElementNode. The motivating use case there would be able to inject "widget decorators" (in prosemirror terms) that sit before or after specific nodes to facilitate UI that is "outside" of the document. The sorts of things we do now with popovers.

DOMImportExtension - the importDOM code is in a much worse shape and is a lot trickier to augment, I've decided to tackle that separately since the export is in a pretty good state and would solve some current pain points.

EditorDOMRenderConfig

This data structure moves responsibility for all DOM rendering (create/update) and export to a single configuration in the editor. These $createDOM, $exportDOM, $updateDOM, etc. properties are all functions which are eventually responsible for calling their respective node methods (at least by default).

The trick here is that we can wrap these implementations with middleware style functions that can be composed to override or otherwise run code that happens "around" the default implementations. This is very difficult to do with the existing infrastructure, especially when writing code that needs to target all nodes, all nodes with some specific NodeState, etc. Since they are middleware, they have the ability to call the $next() function to get the result of the next implementation (e.g. "calling super" and then enhancing its result) or not (to completely override).

DOMRenderExtension

This provides a mechanism to compile the EditorDOMRenderConfig using composable configuration, targeting either all nodes with '*' or some subset of nodes by an array of NodeClass or $isNodeClass guards. This first pass is a relatively blunt approach but we can build more specific extensions to consolidate this wrapping in the future for optimization reasons.

Examples:

Enhancing TextNode export to remove the 'white-space' style unless it's necessary to support the encoding of the content:

domOverride([TextNode], {
  $exportDOM(node, $next) {
    const result = $next();
    if (
      $getRenderContextValue(RenderContextRoot) &&
      isHTMLElement(result.element) &&
      result.element.style.getPropertyValue('white-space') ===
        'pre-wrap' &&
      // we know there aren't tabs or newlines but if there are
      // leading, trailing, or adjacent spaces then we need the
      // pre-wrap to preserve the content
      !/^\s|\s$|\s\s/.test(result.element.textContent)
    ) {
      result.element.style.setProperty('white-space', null);
      if (result.element.style.cssText === '') {
        result.element.removeAttribute('style');
      }
    }
    return result;
  },
})

Adding an arbitrary id property to any node (e.g. for supporting deep linking)

domOverride('*', {
  $exportDOM(node, $next) {
    const result = $next();
    const id = $getState(node, idState);
    if (id && isHTMLElement(result.element)) {
      result.element.setAttribute('id', id);
    }
    return result;
  },
})

New APIs

All new APIs are marked `@experimental` and are subject to change.

lexical

Export	Kind	Description
EditorDOMRenderConfig	interface	Configuration for DOM rendering: $createDOM, $getDOMSlot, $exportDOM, $extractWithChild, $updateDOM, $shouldInclude, $shouldExclude
DEFAULT_EDITOR_DOM_CONFIG	const	The default config that delegates to node methods
$getEditorDOMRenderConfig(editor?)	function	Returns the editor's DOM render config (or default)
$isLexicalNode(node)	function	Type guard for LexicalNode instances
CreateEditorArgs.dom	property	Optional Partial<EditorDOMRenderConfig> to override rendering at editor creation

@lexical/html

Export	Kind	Description
DOMRenderExtension	extension	Compiles DOMRenderMatch overrides into an EditorDOMRenderConfig
domOverride(nodes, config)	function	Convenience function for constructing DOM overrides with type inference
$generateDOMFromNodes(container, selection?, editor?)	function	Populate a container with the editor's DOM using EditorDOMRenderConfig
$generateDOMFromRoot(container, root?)	function	Like above but includes the root node itself
$getRenderContextValue(cfg, editor?)	function	Read a value from the active render context
$withRenderContext(pairs, editor?)	function	Execute a callback within a render context
RenderContextRoot	const	Context state: true when export was initiated from the document root
RenderContextExport	const	Context state: true during $generateHtmlFromNodes
contextValue(cfg, value)	function	Create a context pair to set a value
contextUpdater(cfg, updater)	function	Create a context pair to transform a value
DOMRenderConfig	type	Configuration for DOMRenderExtension
DOMRenderMatch<T>	type	Override definition for node rendering/export
NodeMatch<T>	type	Match a node by class or guard
AnyDOMRenderMatch	type	Any DOMRenderMatch
DOMRenderExtensionOutput	type	Output of DOMRenderExtension
RenderStateConfig<V>	type	Context configuration for render context
AnyRenderStateConfig	type	Any RenderStateConfig
AnyRenderStateConfigPairOrUpdater	type	Any setter/updater for RenderStateConfig
ContextPairOrUpdater<Ctx, V>	type	Set or update a context value

Test plan

Currently it's primarily some minimal tests that show the legacy support works the same way that the legacy code does

Also ships a dev-node-state-style example that demonstrates one of the use cases (having NodeState apply styles to any node both in create and export).

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview, Comment	Apr 17, 2026 6:48pm
lexical-playground	Ready	Preview, Comment	Apr 17, 2026 6:48pm