Quick Guide: Lexical is a lightweight (22kb min+gzip) extensible text editor framework. Use

LexicalComposer

for React setup with plugins as child components. Extend via the node system (ElementNode, TextNode, DecoratorNode), command system (createCommand + priorities), and transforms. EditorState is immutable -- all mutations happen inside

editor.update()

. Use

$

-prefixed functions only inside update/read closures. Current: v0.42.x (pre-1.0)

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

$

$getRoot

$getSelection

$createTextNode

editor.update()

editor.read()

nodes

initialConfig

useEffect

• Building rich text editors with custom formatting and embedded content
• Creating editors with custom node types (mentions, embeds, code blocks)
• Implementing collaborative editing with operational transforms
• Building structured content editors (not just plain text)

• Plain text inputs without formatting (use a standard

  <textarea>

  )
• Simple markdown editing without live preview (use a textarea with markdown parsing)
• Editors that need pure decorations without document mutation (Lexical decorator nodes mutate content)

• React setup with LexicalComposer, plugins, and initialConfig
• Node system: ElementNode, TextNode, DecoratorNode, custom nodes
• Command system: createCommand, priorities, dispatching, propagation
• Transforms for automatic node mutations
• EditorState immutability and the update lifecycle
• JSON and HTML serialization

• examples/core.md - Editor setup, plugins, commands, transforms
• examples/custom-nodes.md - Custom ElementNode, TextNode, DecoratorNode, NodeState API
• examples/serialization.md - JSON/HTML serialization, import/export, headless usage
• reference.md - Decision frameworks, command priority table, anti-patterns

• Immutable EditorState: The editor maintains a frozen state snapshot. Mutations happen inside

  editor.update()

  closures that clone the state, apply changes, then reconcile to DOM.

• $

  -function convention: Functions prefixed with

  $

  (like

  $getRoot()

  ,

  $getSelection()

  ) must run inside

  editor.update()

  or

  editor.read()

  closures -- similar to React hooks requiring a component context.
• Plugin = React component: In the React binding, a plugin is a React component rendered as a child of

  <LexicalComposer>

  . It accesses the editor via

  useLexicalComposerContext()

  and registers commands/transforms/listeners in

  useEffect

  .
• Command-driven architecture: User interactions and plugin communication flow through typed commands with priority-based listeners, enabling plugins to intercept or augment behavior.
• Node-driven content model: Content is a tree of typed nodes. Custom content types (mentions, embeds, polls) are custom node classes.

• Rich text editing with custom formatting and embedded content
• Content editors requiring structured output (not just HTML strings)
• Editors needing accessibility and screen reader support
• Applications requiring server-side rendering or headless processing of editor content

• Simple text inputs (a

  <textarea>

  is simpler and lighter)
• Editors needing pure decorations that don't affect document content
• Projects requiring a stable 1.0 API (Lexical is pre-1.0, APIs may change)

ElementNode

createDOM()

updateDOM()

TextNode

createDOM()

updateDOM()

DecoratorNode<T>

decorate()

1. static getType()

   -- unique string identifier

2. static clone(node)

   -- create copy for state snapshots

3. createDOM()

   -- return the HTMLElement representation

4. updateDOM()

   -- return

   false

   if existing DOM can be reused

5. exportJSON()

   /

   static importJSON()

   -- serialization
6. Registration in

   initialConfig.nodes

import { DecoratorNode } from "lexical";
import type { LexicalNode, NodeKey, EditorConfig } from "lexical";

export class ImageNode extends DecoratorNode<JSX.Element> {
  __src: string;
  __alt: string;

  static getType(): string {
    return "image";
  }

  static clone(node: ImageNode): ImageNode {
    return new ImageNode(node.__src, node.__alt, node.__key);
  }

  constructor(src: string, alt: string, key?: NodeKey) {
    super(key);
    this.__src = src;
    this.__alt = alt;
  }

  createDOM(_config: EditorConfig): HTMLElement {
    return document.createElement("div");
  }

  updateDOM(): boolean {
    return false;
  }

  decorate(): JSX.Element {
    return <img src={this.__src} alt={this.__alt} />;
  }
}

__

• Calling

  $

  -prefixed functions outside

  editor.update()

  or

  editor.read()

  -- causes runtime errors with no compile-time warning
• Missing node registration in

  initialConfig.nodes

  -- custom nodes silently fail or throw when the editor encounters them
• Transforms without preconditions -- unconditional mutations retrigger the transform infinitely, freezing the editor
• Using

  editor.update()

  inside an update listener to modify state -- breaks undo/redo history and causes extra renders; use transforms instead
• Forgetting

  useEffect

  cleanup for register calls -- leaks listeners, causes stale references after component unmount

• Direct DOM manipulation instead of using the node/command system -- bypasses the reconciler, causes state-DOM desync
• Storing non-JSON-serializable values in node properties (functions, Maps, Sets) -- breaks serialization silently
• Using

  editor.setEditorState()

  without cloning -- can cause unexpected focus changes; use

  editorState.clone(null)

  to prevent auto-focus
• Naming custom node

  getType()

  with a non-unique string -- collides with other nodes, causes deserialization failures
• Using

  new MyNode()

  directly instead of

  $createMyNode()

  factory -- bypasses the node replacement system (

  $applyNodeReplacement

  )
• Single underscore node properties (

  _value

  instead of

  __value

  ) -- may be mangled by minifiers, breaking node access

• console.log

  in

  onError

  callback with no rethrow -- silently swallows editor errors; rethrow or send to error tracking

• editor.update()

  batches synchronously but reconciles asynchronously -- use

  { discrete: true }

  option when you need synchronous DOM commit (e.g., before reading DOM measurements)
• Node property names must use

  __

  prefix convention -- single underscore properties may be mangled by minifiers

• DecoratorNode.decorate()

  returns a component that Lexical renders outside the normal React tree -- state management in decorator components needs care
• The

  onError

  callback in

  initialConfig

  receives errors from update closures -- if you don't rethrow, Lexical tries to recover gracefully

• TextNode

  modes:

  "token"

  makes text immutable (like a chip),

  "segmented"

  deletes word-by-word
• CSS

  transition

  does not work for animations based on node removal -- Lexical reconciles by removing DOM nodes, not hiding them
• The NodeState API (v0.26+) is experimental -- APIs may change without extended deprecation

All code must follow project conventions in CLAUDE.md

$

$getRoot

$getSelection

$createTextNode

editor.update()

editor.read()

nodes

initialConfig

useEffect