Skip to main content

@lexical/headless/HeadlessExtension

Variables​

HeadlessExtension​

const HeadlessExtension: LexicalExtension<ExtensionConfigBase, "@lexical/headless/Headless", void, unknown>

Defined in: packages/lexical-headless/src/HeadlessExtension.ts:32

Marks an editor as headless. Use it with buildEditorFromExtensions for an editor that will never be attached to the DOM, for example on a server or in tests.

An editor with no root element already skips reconciliation and DOM selection, so this extension is not required for that. What it adds:

  • editor.setRootElement(element) throws, so the editor cannot be attached to the DOM by mistake. setRootElement(null) is still allowed, which is what editor.dispose() calls.
  • Nested editors created with this editor as their parentEditor are headless too.
  • Extensions that only do DOM work can check the flag and skip registering it, as the code gutter in @lexical/code-core does.

Unlike createHeadlessEditor, listener registration methods such as registerRootListener keep working, so extensions that register them can be used in a headless editor. Those listeners never see a root element.