{"owner":"facebook","repo":"lexical","hasSkills":true,"totalSkillsCount":96,"totalTokensCount":140729,"categories":["root-instruction","claude-rule","plugin-manifest","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md","packages/lexical-a11y/README.md","packages/lexical-clipboard/README.md","packages/lexical-code-core/README.md","packages/lexical-code-prism/README.md","packages/lexical-code-shiki/README.md","packages/lexical-code/README.md","packages/lexical-compiler/README.md","packages/lexical-devtools-core/README.md","packages/lexical-devtools/README.md","packages/lexical-dragon/README.md","packages/lexical-eslint-plugin/README.md","packages/lexical-eslint-plugin/__tests__/integration/README.md","packages/lexical-extension/README.md","packages/lexical-fast-check/README.md","packages/lexical-file/README.md","packages/lexical-hashtag/README.md","packages/lexical-headless/README.md","packages/lexical-history/README.md","packages/lexical-html/README.md","packages/lexical-internal/README.md","packages/lexical-link/README.md","packages/lexical-list/README.md","packages/lexical-mark/README.md","packages/lexical-markdown/README.md","packages/lexical-mdast/README.md","packages/lexical-offset/README.md","packages/lexical-overflow/README.md","packages/lexical-plain-text/README.md","packages/lexical-react/README.md","packages/lexical-rich-text/README.md","packages/lexical-selection/README.md","packages/lexical-table/README.md","packages/lexical-tailwind/README.md","packages/lexical-text/README.md","packages/lexical-utils/README.md","packages/lexical-website/README.md","packages/lexical-website/docs/collaboration/_category_.json","packages/lexical-website/docs/collaboration/faq.md","packages/lexical-website/docs/collaboration/react.md","packages/lexical-website/docs/concepts/_category_.json","packages/lexical-website/docs/concepts/commands.md","packages/lexical-website/docs/concepts/compared-with-prosemirror.md","packages/lexical-website/docs/concepts/document-model.md","packages/lexical-website/docs/concepts/dom-events.md","packages/lexical-website/docs/concepts/editor-state.md","packages/lexical-website/docs/concepts/headless.md","packages/lexical-website/docs/concepts/history.md","packages/lexical-website/docs/concepts/key-management.md","packages/lexical-website/docs/concepts/keyboard-accessibility.md","packages/lexical-website/docs/concepts/listeners.md","packages/lexical-website/docs/concepts/named-slots.md","packages/lexical-website/docs/concepts/node-cloning.md","packages/lexical-website/docs/concepts/node-replacement.md","packages/lexical-website/docs/concepts/node-state.md","packages/lexical-website/docs/concepts/one-lexical-per-app.md","packages/lexical-website/docs/concepts/read-only.md","packages/lexical-website/docs/concepts/selection.md","packages/lexical-website/docs/concepts/shadow-dom.md","packages/lexical-website/docs/concepts/transforms.md","packages/lexical-website/docs/concepts/traversals.md","packages/lexical-website/docs/design.md","packages/lexical-website/docs/error.md","packages/lexical-website/docs/extensions/defining-extensions.md","packages/lexical-website/docs/extensions/design.md","packages/lexical-website/docs/extensions/included-extensions.md","packages/lexical-website/docs/extensions/intro.md","packages/lexical-website/docs/extensions/peer-dependencies.md","packages/lexical-website/docs/extensions/react.md","packages/lexical-website/docs/extensions/signals.md","packages/lexical-website/docs/faq.md","packages/lexical-website/docs/getting-started/_category_.json","packages/lexical-website/docs/getting-started/devtools.md","packages/lexical-website/docs/getting-started/supported-browsers.md","packages/lexical-website/docs/getting-started/theming.md","packages/lexical-website/docs/intro.md","packages/lexical-website/docs/maintainers-guide-link.md","packages/lexical-website/docs/maintainers-guide.md","packages/lexical-website/docs/react/_category_.json","packages/lexical-website/docs/react/create_plugin.md","packages/lexical-website/docs/react/faq.md","packages/lexical-website/docs/react/index.md","packages/lexical-website/docs/react/plugins.md","packages/lexical-website/docs/serialization/_category_.json","packages/lexical-website/docs/serialization/dom-import.md","packages/lexical-website/docs/serialization/dom-render.md","packages/lexical-website/docs/serialization/legacy.md","packages/lexical-website/docs/serialization/markdown-mdast.md","packages/lexical-website/docs/serialization/serialization.md","packages/lexical-website/docs/testing.md","packages/lexical-website/plugins/example-source/README.md","packages/lexical-website/src/data/README.md","packages/lexical-yjs/README.md","packages/lexical/README.md","packages/lexical/src/__bench__/README.md"],"skills":{"AGENTS.md":"# Lexical Agent Guide\n\nThis file provides detailed guidance for AI agents and automated tools working with the Lexical codebase.\n\n## Build, Test, and Development Commands\n\n### Building\n- `pnpm run build` - Build all packages in development mode\n- `pnpm run build-prod` - Clean and build all packages in production mode\n- `pnpm run build-release` - Build production release with error codes\n- `pnpm run build-types` - Build TypeScript type definitions and validate them\n\n### Testing\n- `pnpm run test-unit` - Run all unit tests (Vitest, Node/jsdom)\n- `pnpm run test-unit-watch` - Run unit tests in watch mode\n- `pnpm run test-browser` - Run browser-mode unit tests (Vitest + Playwright, real browser)\n- `pnpm run test-browser-watch` - Run browser-mode tests in watch mode\n- `pnpm run test-e2e-chromium` - Run E2E tests in Chromium (requires dev server running)\n- `pnpm run test-e2e-firefox` - Run E2E tests in Firefox\n- `pnpm run test-e2e-webkit` - Run E2E tests in WebKit\n- `pnpm run debug-test-e2e-chromium` - Run E2E tests in debug mode (headed)\n- `pnpm run debug-test-unit` - Debug unit tests with inspector\n\nFor E2E testing workflow:\n1. Start the dev server: `pnpm run start` (or `pnpm run dev` if you don't need collab)\n2. In another terminal: `pnpm run test-e2e-chromium`\n\n### Development Servers\n- `pnpm run start` - Start playground dev server + collab server (http://localhost:3000)\n- `pnpm run dev` - Start only the playground dev server (no collab)\n- `pnpm run start:website` - Start Docusaurus website (http://localhost:3001)\n- `pnpm run collab` - Start collab server on localhost:1234\n\n### Code Quality\n- `pnpm run lint` - Run ESLint on all files\n- `pnpm run lint:fix` - Auto-fix lint issues\n- `pnpm run prettier` - Check code formatting\n- `pnpm run prettier:fix` - Auto-fix formatting issues\n- `pnpm run flow` - Run a full foreground Flow check (does not reuse a server)\n- `pnpm run tsc` - Run TypeScript compiler\n- `pnpm run ci-check` - Run all checks (TypeScript, Flow, Prettier, ESLint)\n\n**Never commit changes to `scripts/error-codes/codes.json`.**\nThat edit is not yours to make — revert it to the state of\n`main` before staging, and never `git add` the file.\n\n### Searching and refactoring\n\nPrefer **ast-grep** over line-oriented regex (`grep`/`sed`) for anything\nstructural — matching or rewriting imports, call sites, JSX, type\nannotations, etc. Regexes miss multi-line forms (a symbol on its own line\ninside a multi-line `import { ... }` block) and produce false positives\n(`IS_APPLE` matching inside `IS_APPLE_WEBKIT`); ast-grep matches the syntax\ntree, so it does neither.\n\nIt isn't a dependency, so run it via npx (the CLI binary is `ast-grep`, not\nthe shadow-utils `sg` that may be on `PATH`):\n\n```sh\n# Find every import of something from '@lexical/utils' (ts and tsx are\n# separate grammars, so pass -l for each; add --json=compact to post-process)\nnpx --package @ast-grep/cli ast-grep run \\\n -p \"import { \\$\\$\\$NAMES } from '@lexical/utils'\" -l ts packages\n```\n\nMetavariables (`$NAME`, `$$$LIST`) capture nodes for reporting or rewriting\nwith `--rewrite`. Reach for it whenever a change spans many files and must be\nprecise — e.g. moving symbols that `@lexical/utils` merely re-exports back to\na direct `lexical` import.\n\n### Extension source imports\n\nImport from the `@lexical/extension` barrel across package boundaries. Within\n`packages/lexical-extension`, use relative imports and re-exports. Do not\nmanually rewrite these source imports to `@lexical/extension/*`: ESLint\nenforces the source convention, and `@lexical/compiler`'s `subpathImports`\npass rewrites them in all published package builds, including www. Public\nsibling entries stay external so shared modules such as signals retain one\ninstance. Helpers with only one owning entry live under `src/internal` and\nare bundled into that entry, without exposing additional public subpaths.\nDownstream users may import either the barrel or public subpaths.\n\n### Tree-shaking annotations\n\nModule-scope calls to the side-effect-free factories (`defineExtension`,\n`configExtension`, `safeCast`, `createCommand`, `createState`,\n`defineImportRule`, etc.) need a `/* @__PURE__ */` annotation so bundlers\ncan drop unused definitions from application bundles. **Do not write those\nannotations by hand** — they are injected at build time by\n`@lexical/compiler` (`packages/lexical-compiler`), which\nruns as a Rollup plugin in `scripts/build.mjs` for the published bundles\nand as a Vite plugin in `scripts/vite/lexicalMonorepoPlugin.ts` for\neverything the monorepo builds from source. The published package is also\nwhat consumers add to their own build when they compile Lexical from its\n`source` export condition rather than from `dist`.\n\nA hand-written annotation on one of these calls is a lint error\n(`@lexical/internal/no-pure-annotation`), and the rule is autofixable, so a\nbranch written before the transform existed migrates with\n`pnpm run lint:fix`. Annotations on anything else — a third-party factory, or\na call inside a function body, where the build never injects one — are left\nalone.\n\nWhen adding a new factory of this kind, annotate its definition with\n`@__NO_SIDE_EFFECTS__`. That alone is enough for calls in the same package to\nbe annotated; add its name to `PURE_FACTORY_FUNCTIONS` in\n`packages/lexical-compiler/src/LexicalCompiler.mjs` so that\ncalls in code that imports it by package name are too. An object whose\nmethods build values and touch nothing else (like `@lexical/html`'s `sel`) is\nmarked `@lexical-pure-namespace` instead, so that `sel.tag('p')` is annotated\nthe way a factory call is.\n\nThe build runs with `strict`, which fails on a call inside one of these\ndefinitions that nothing has established is side-effect free — such a call\npins the definition into every bundle that imports the module, however well\nannotated the definition itself is. If it stops you, either make the call\nlazy (a `nodes: () => [...]` callback is not evaluated at module scope), or\ndeclare the function side-effect free so its calls are annotated too. A\nthird-party factory that cannot be declared is annotated by hand at the call\nsite, which is what the remaining hand-written annotations in the tree are.\n\nFactory calls are not the only module-scope statements that pin a module.\nesbuild and webpack keep, as a side effect, any property read at module scope\n(`navigator.userAgent`, `Date.now`, `SomeExtension.name`), any call or `new`\nthey were not told is pure (`new RegExp(...)`, `Object.freeze(...)`,\n`[...].join(',')`), an array or object spread, an `in` test, a `try`\nstatement, a mutation (`table.push(...)`, `Klass.static = ...`), a class with\na computed member (`[SOME_SYMBOL]?: number` — write `declare` on it), and an\nIIFE — together with everything the statement references. One\n`LexicalEditor.version = ...` after the class kept nearly all of `lexical` in\na bundle that imported only `createCommand` (#9120). Move such work into a\nfunction declared `@__NO_SIDE_EFFECTS__` and call it at module scope, so the\nbuild annotates the call; annotate a call to a builtin or to a third-party\nfunction (`/* @__PURE__ */ forwardRef(...)`) by hand. Two tests enforce this\nby bundling a bare `import 'pkg'` of every entry with esbuild and requiring\nthat nothing is retained: `scripts/__tests__/unit/treeShakingSource.test.ts`\non the sources (runs with `pnpm run test-unit`) and\n`scripts/__tests__/integration/tree-shaking.test.mjs` on the published\nbuilds. A failure prints the retained code; its first statement is usually\nthe culprit.\n\nA factory whose body is a trivial expression over its own arguments (like\n`safeCast`, `defineExtension`, or `configExtension`) is additionally marked\n`@lexical-inline
` and listed in that file's `INLINE_FACTORIES`: the\nbuild replaces calls to it with the expression it would have returned, which\nneeds no annotation at all. **The body of a marked function is reproduced by\nthe build**, so keep it trivial — `packages/lexical-compiler`'s unit\ntests compare what the transform emits against what the real function returns\nand will fail if the two drift apart.\n\n## High-Level Architecture\n\n### Core Concepts\n\nLexical is built around several key architectural concepts that work together:\n\n**Editor Instance** - Created via `createEditor()`, wires everything together. Manages the EditorState, registers listeners/commands/transforms, and handles DOM reconciliation.\n\n**EditorState** - Immutable data model representing the editor content. Contains:\n- A node tree (hierarchical structure of LexicalNodes)\n- A selection object (current cursor/selection state)\n- Fully serializable to/from JSON\n\n**`$` Functions Convention** - Functions prefixed with `$` (e.g., `$getRoot()`, `$getSelection()`) can ONLY be called within:\n- `editor.update(() => {...})` - for mutations\n- `editor.read(() => {...})` - for read-only access\n- Node transforms and command handlers (which have implicit update context)\n\nThis is similar to React hooks' restrictions but enforces synchronous context instead of call order.\n\n**Double-Buffering Updates** - When `editor.update()` is called:\n1. Current EditorState is cloned as work-in-progress\n2. Mutations modify the work-in-progress state\n3. Multiple synchronous updates are batched\n4. DOM reconciler diffs and applies changes\n5. New immutable EditorState becomes current\n\n**Node Immutability & Keys** - All nodes are recursively frozen after reconciliation. Node methods automatically call `node.getWritable()` to create mutable clones. All versions of a logical node share the same runtime-only key, allowing node methods to always reference the latest version from the active EditorState.\n\n### Monorepo Structure\n\nThis is a monorepo with packages in `packages/`:\n\n**Core Packages:**\n- `lexical` - Core framework (Editor, EditorState, base nodes, selection, updates)\n- `@lexical/react` - React bindings (LexicalComposer, plugins as components)\n- `@lexical/headless` - Headless editor for server-side/testing\n\n**Feature Packages** (extend core with nodes/commands/utilities):\n- `@lexical/rich-text` - Rich text editing (headings, quotes, etc.)\n- `@lexical/plain-text` - Plain text editing\n- `@lexical/extension` - Extend editor functionality\n- `@lexical/list` - List nodes (ordered/unordered/checklist)\n- `@lexical/table` - Table support\n- `@lexical/code` - Code block with syntax highlighting\n- `@lexical/link` - Link nodes and utilities\n- `@lexical/markdown` - Markdown import/export\n- `@lexical/html` - HTML serialization\n- `@lexical/history` - Undo/redo\n- `@lexical/yjs` - Real-time collaboration via Yjs\n- And many more...\n\n**Development Packages:**\n- `lexical-playground` - Full-featured demo application\n- `lexical-website` - Docusaurus documentation site\n\n### Key Architectural Patterns\n\n**Extensions** - Extensions should be used to add features and configuration\nto an editor. The set of extensions in an editor must be determined when the\neditor is created with `buildEditorFromExtensions`. Extensions with\nfunctionality that can be toggled on or off typically have a `disabled`\nconfiguration property and output signal that defaults to `false`. See the\nlexical-extension package and the supporting code in lexical for\nmore examples and implementation details.\n\n```tsx\nexport interface MyConfig {\n disabled: boolean;\n}\nexport const MyExtension = defineExtension({\n build: (_editor, config, _state) => namedSignals(config),\n config: safeCast({ disabled: false }),\n name: '@lexical/docs/My',\n nodes: () => [MyNode],\n register: (editor, _config, state) => {\n const {disabled} = state.getOutput();\n return effect(() => {\n if (!disabled.value) {\n return editor.registerUpdateListener(({editorState}) => {\n // React to updates\n });\n }\n })\n },\n})\n```\n\n**Plugin System (React)** - Plugins are a legacy pattern for React components\nto hook into the editor lifecycle, extensions should be preferred for new code:\n```jsx\nfunction MyPlugin() {\n const [editor] = useLexicalComposerContext();\n useEffect(() => {\n return editor.registerUpdateListener(({editorState}) => {\n // React to updates\n });\n }, [editor]);\n return null;\n}\n```\n\n**Command Pattern** - Commands are the primary communication mechanism:\n- Create with `createCommand()`\n- Dispatch with `editor.dispatchCommand(command, payload)`\n- Handle with `editor.registerCommand(command, handler, priority)`\n- Handlers propagate by priority until one stops propagation\n\n**Node Transforms** - Registered via `editor.registerNodeTransform(NodeClass, transform)`. Called automatically during updates when nodes of that type change. Have implicit update context.\n\n**Listeners** - All `editor.register*()` methods return cleanup functions for easy unsubscription.\n\n## Type System\n\nThis codebase uses **both TypeScript and Flow**:\n- Source files are primarily TypeScript (`.ts`, `.tsx`)\n- Flow type definitions are generated in `packages/*/flow/` directories\n- Run `pnpm run flow` to check Flow types\n- Run `pnpm run tsc` to check TypeScript types\n- Both are checked in CI via `pnpm run ci-check`\n\nWhen adding/modifying APIs, types must be maintained for both systems.\n\n## Backwards Compatibility\n\n**All changes MUST be backwards compatible.** Lexical is a widely-adopted OSS library, and breaking changes ripple out to every downstream consumer.\n\n- Do NOT remove or rename existing public APIs, exported functions, types, or `$` functions. Add new APIs alongside the old ones instead.\n- Do NOT change the signature, return type, or behavior of existing public APIs in ways that could break callers. Prefer additive, optional parameters.\n- Preserve the serialization format of `EditorState` and node JSON. Serialized content produced by older versions must continue to deserialize correctly.\n- If an API genuinely must change, deprecate the old one first (keep it working, document the replacement) rather than removing it outright.\n- When in doubt, assume external code depends on the current behavior and keep it intact.\n\n## Dependencies: Lexical is a singleton within one app\n\nAn application must resolve exactly one copy of `lexical`, and one copy of each\n`@lexical/*` package it uses. The active editor and editor state are\nmodule-scope variables in `LexicalUpdates.ts`, node registration and\n`instanceof LexicalNode` compare class references, and commands are object\nidentities from `createCommand()` — none of which survive a second copy of the\nmodule. Two copies also mean two versions, which is API drift inside one editor.\n\nThe boundary is the app, not the page: several self-contained apps, each with\nits own bundled Lexical, can coexist on one page (`isLexicalEditor` is an\n`instanceof` check precisely to support that). They just cannot interoperate —\nnodes, editors, `EditorState`s, selections and commands must never be passed\nacross such a boundary, only serialized data.\n\n- Inside this monorepo, packages depend on siblings with `\"lexical\":\n \"workspace:*\"`; `pnpm publish` rewrites that to the exact published version,\n so every `@lexical/*` release pins the matching `lexical`. Keep that pattern\n when adding a package — do not hand-write a version range.\n- A **library** published on top of Lexical (anything outside this repo that\n imports `lexical` or `@lexical/*`) declares those packages in\n `peerDependencies`, plus `devDependencies` for its own build and tests, never\n in `dependencies`. Apps bring their own Lexical and own the version.\n- Code under `examples/` and `packages/lexical-playground` are applications, so\n they depend on Lexical directly — that is correct and should stay.\n\nThe user-facing version of this rule lives in\n`packages/lexical-website/docs/concepts/one-lexical-per-app.md`; keep the two in\nsync when either changes.\n\n## Important Development Notes\n\n### Reconciliation and Updates\n- `editor.read(...)` or `editor.read('force-commit', ...)` flushes pending updates first, then provides consistent reconciled state\n- `editor.read('pending', ...)` reads the pending state (like `editor.update(...)`, but read-only)\n- `editor.read('latest', ...)` reads the latest consistent reconciled state\n- Inside `editor.update()`, you see pending state (transforms/reconciliation not yet run)\n- `editor.getEditorState().read()` always uses latest reconciled state, but prefer `editor.read('latest', ...)` in new code\n- Updates can be nested: `editor.update(() => editor.update(...))` is allowed but strongly discouraged\n- Do NOT nest updates in reads, or use a force-commit in an update\n\n### Node References\nAlways access node properties/methods within read/update context. Nodes automatically resolve to their latest version via their key. Don't store node references across update boundaries.\n\n### Testing Strategy\n- **Unit tests** - Vitest, located in `packages/**/__tests__/unit/**/*.test.{ts,tsx}`.\n Add `// @vitest-environment node` after the copyright header for tests that\n only exercise editor state, headless behavior, or pure utilities. DOM tests\n use jsdom with `vmThreads` on Node 24.9+, which reuses the jsdom implementation\n while keeping each file's window and module graph isolated. Older Node\n versions use isolated forks because their VM contexts cannot load jsdom's\n `require(esm)` dependencies. Platform-mocked tests depend on module isolation.\n Compiler tests run with `scripts-unit` in\n ordinary Node workers because native build tools are not VM-realm-safe.\n Use `DOMParser` to parse HTML in DOM tests and iframes for separate-window\n tests. Reserve direct JSDOM construction for Node fixtures or CSSOM behavior\n that jsdom's DOMParser lacks.\n- **Browser tests** - Vitest browser mode driven by the Playwright runner, located in\n `packages/**/__tests__/browser/**/*.test.{ts,tsx}`. Use these for behavior that depends on\n a real layout/selection engine instead of stubbing the missing jsdom functionality from\n `vitest.setup.mts` (e.g. `Range.getBoundingClientRect`, the Selection API). Run with\n `pnpm run test-browser`; the browser set is controlled by the `VITEST_BROWSER` env var\n (comma-separated, default `chromium`). Prefer building editors with the extension APIs\n (`buildEditorFromExtensions`, or `LexicalExtensionComposer`/`LexicalExtensionEditorComposer`\n in React).\n - **Do not use `using`/`Disposable` in browser tests (or any browser-facing code).**\n Explicit Resource Management (`using`, `Symbol.dispose`, `Disposable`) is not supported\n in WebKit/Safari yet, so the syntax throws a `SyntaxError` there. `using` is fine in unit\n tests (jsdom/Node), but browser tests should clean up with\n `onTestFinished(() => editor.dispose())` instead — `editor.dispose()` is a plain method\n available on the result of `buildEditorFromExtensions`.\n- **E2E tests** - Playwright, located in `packages/lexical-playground/__tests__/e2e/**/*.spec.{ts,mjs}`\n- E2E tests require the playground dev server running\n- Use `pnpm run debug-test-e2e-chromium` to debug E2E tests with browser UI\n\n### Custom Nodes\nWhen creating custom nodes:\n1. Extend a base node class (TextNode, ElementNode, DecoratorNode). The\n constructor must work with no arguments.\n2. Implement `$config()` with `this.config('type', {extends: BaseNode, json:\n schema})`, where `schema` is built with `nodeSchema()({...})`\n as a module-scope `const` above the class. Written inline in `$config()`,\n it makes TypeScript skip checking the class without a diagnostic.\n Declare every property inherent to the node in it, and declare each one\n stored verbatim in a field with\n `withField(stringValue(), {field: '__name'})`. Initialize that field in\n the class (`__name: string = '';`) so it is an own property of a fresh\n node. Use `withAccessors` only where a property is not a plain field.\n3. Do not hand-write `clone`, `importJSON`, `exportJSON` or\n `updateFromJSON`: `$config` derives them from the schema, and it carries\n every property declared with `withField` across a clone. A field missing\n from the schema is not carried, so it is lost the first time a later\n update clones the node; declare it with `withField` rather than writing\n `afterCloneFrom`. Ad-hoc data that is not inherent to the node type\n belongs in NodeState (`createState`), which clones on its own. Write\n `afterCloneFrom` only for storage neither covers, such as a property\n declared through accessors on both sides whose value is not one field\n (one that is can name it: `setter: {field: '__ids', method: 'setIDs'}`\n in `MarkNode`). Call `super.afterCloneFrom(prevNode)` first, and copy\n every field of the class, schema fields included: Lexical does not add\n to a class's own `afterCloneFrom`.\n4. Implement `createDOM()` and `updateDOM()` (and `decorate()` for a\n DecoratorNode). Keep `exportDOM()` on the class when the default export\n is not enough.\n5. For HTML import, prefer `defineImportRule` rules registered by the\n extension that provides the node: list `CoreImportExtension` and\n `configExtension(DOMImportExtension, {rules: [...]})` in its\n `dependencies` (see `ListExtension`, and `ListImportRules` for the rules,\n in `@lexical/list`). Both APIs are `@experimental`, and the rules only\n apply where the editor routes HTML through the pipeline; see\n `packages/lexical-website/docs/serialization/dom-import.md`.\n `importDOM()`, which that page calls legacy, is not deprecated yet, but\n its deprecation is planned.\n6. Register with an extension (`nodes: () => [YourNode]`) or editor config.\n7. Export a `$createYourNode()` factory built on `$create(YourNode)` and the\n node's setters, and a `$isYourNode()` guard.\n\nThe full schema reference is\n`packages/lexical-website/docs/serialization/serialization.md`; the cloning\nrules are in `packages/lexical-website/docs/concepts/node-cloning.md`.\n\n### Shadow DOM and iframe realm safety\n\nLexical supports editors whose root element lives inside a Shadow DOM or an\n`\n\n## Sharing one Yjs document between editors\n\nBy default a binding uses the `XmlText` shared type named `root` on the Yjs\n`Doc`, so each editor needs its own document. Two options let several editors\nlive in one document instead, which is what applications like collaborative\nsticky notes or comment threads usually want:\n\n- `rootName` picks a different top-level shared type, one per editor:\n\n```jsx\n\n```\n\n- `getXmlText` resolves the root yourself, for roots that are not top-level\n shared types (for example an `XmlText` stored in a `Y.Map`). It takes\n precedence over `rootName`:\n\n```jsx\nconst getXmlText = useCallback(\n (doc) => doc.getMap('notes').get(noteId),\n [noteId],\n);\n\n\n```\n\nGive each editor its own `id`, as above: the `id` keys the document map and the\nremote-cursor highlight registry, both of which are shared across the page, so\ntwo editors mounted under one `id` overwrite each other's entries.\n\nBoth options are also available on `createYjsBinding` for non-React usage.\n\n:::warning\n\nThe root is chosen when the binding is created, and a mounted editor cannot be\nrepointed at another root: changing `rootName` or `getXmlText` afterwards has no\neffect. To switch documents, remount the **editor** — put a `key` that changes\nwith the document on the component that owns the `LexicalComposer`. Remounting\nonly the plugin is not enough: the editor would keep the previous document's\ncontent and write it into the newly selected root.\n\n:::\n\n`getXmlText` runs while the binding is constructed, before the provider has\nsynced, so it has to resolve the root from whatever the local `Doc` holds at\nthat moment — reaching into a `Y.Array` that the server has not sent yet throws.\nEither mount the editor only once the note exists locally, or have the callback\ncreate the missing shared type. Write it to be idempotent: it can run more than\nonce for one editor (React StrictMode double-invokes render, and a remount\nbuilds a new binding), and a callback that unconditionally stores a new\n`XmlText` would throw away what the previous call stored.\n\nThe returned `XmlText` is checked to be an `XmlText` that is integrated into the\ndocument; that it is not already driving another live binding is yours to\nguarantee, since a second binding over one root takes over the collab nodes\ncached on its shared types.\n\nThe experimental `CollaborationPluginV2__EXPERIMENTAL` (and\n`createBindingV2__EXPERIMENTAL`) take the same two options, except that its\nroot is an `XmlElement`, so the callback is named `getXmlElement`. Create that\nelement as `new Y.XmlElement()` without a `nodeName`, which is how the root is\nrecognized.\n\n## Building collaborative plugins\n\n[Lexical Playground](https://playground.lexical.dev/) features set of the collaboration enabled plugins that integrate with primary document via `useCollaborationContext()` hook. Notable mentions:\n\n- [`CommentPlugin`](https://github.com/facebook/lexical/tree/main/packages/lexical-playground/src/plugins/CommentPlugin) - features use of the separate provider and Yjs room to sync comments.\n- [`ImageComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/ImageComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested caption editor.\n- [`PollOptionComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/PollComponent.tsx) - showcases poll implementation using `name` from the collaboration context.\n- [`StickyComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/StickyComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested editor as well as sticky note position real-time sync.\n\n:::note\n\nWhile these \"playground\" plugins aren't production ready - they serve as a great example of collaborative Lexical capabilities as well as provide a good starting point.\n\n:::\n\n## Custom node property syncing\n\n`@lexical/yjs` syncs custom node properties by constructing a fresh node instance and inspecting its **own enumerable properties**. This means every property that should be synced across peers must be assigned in the constructor, even if the initial value is `undefined`.\n\n:::warning\n\nDeclaring a class property with TypeScript's optional syntax (`foo?: Type`) does **not** guarantee the property exists as an own enumerable property on the instance. Under TypeScript's default compilation settings (target < ES2022 without `useDefineForClassFields`), such declarations produce no initialization code.\n\n:::\n\n### What to do\n\nAlways initialize every node property in the constructor. Conditional initialization such as `if (someValue !== undefined) this.__someValue = someValue` is not enough, because the default construction path still needs to create the property.\n\nFor example:\n\n```ts\n// ✅ Correct — property is guaranteed to be an own property\nclass MyNode extends ElementNode {\n __someValue: string | undefined;\n\n constructor(someValue?: string, key?: NodeKey) {\n super(key);\n this.__someValue = someValue; // explicitly initialized\n }\n}\n\n// ❌ Incorrect — property may not exist as an own property\nclass MyNode extends ElementNode {\n __someValue?: string; // optional syntax without initialization\n\n constructor(key?: NodeKey) {\n super(key);\n // __someValue is never assigned → won't be synced via yjs\n }\n}\n```\n\nIf you use [`NodeState`](../concepts/node-state.md) for your custom properties, this concern does not apply. `NodeState` values are synced correctly without relying on constructor-created enumerable properties.\n\n## Yjs providers\n\nSetting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. Providers manage all that for you and are the perfect starting point for your collaborative app.\n\nSee [Yjs Website](https://docs.yjs.dev/ecosystem/connection-provider) for the list of the officially endorsed providers. Although it's not an exhaustive one.\n","packages/lexical-website/docs/concepts/_category_.json":"{\n \"label\": \"Concepts\",\n \"position\": 3\n}\n","packages/lexical-website/docs/concepts/commands.md":"\n\n# Commands\n\nCommands are a very powerful feature of Lexical that lets you register listeners for events like `KEY_ENTER_COMMAND` or `KEY_TAB_COMMAND` and contextually react to them _wherever_ & _however_ you'd like.\n\nThis pattern is useful for building [`Toolbars`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) or complex extensions and nodes such as [tables](https://github.com/facebook/lexical/tree/main/packages/lexical-table) which require special handling for `selection`, `keyboard events`, and more.\n\nWhen registering a `command` you supply a `priority` and can return `true` to mark it as \"handled\", which stops other listeners from receiving the event. If a command isn't handled explicitly by you, it's likely handled by default in [`RichTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-rich-text/src/index.ts) or [`PlainTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-plain-text/src/index.ts).\n\n## `createCommand(...)`\n\nYou can view the core commands in the [`lexical` API reference](/docs/api/modules/lexical#commands). Other packages define their own, listed under Commands in each package's API reference, such as [`TOGGLE_LINK_COMMAND`](/docs/api/modules/lexical_link#toggle_link_command) in `@lexical/link`. If you need a custom command for your own use case, check out the typed `createCommand(...)` function.\n\n```js\nconst HELLO_WORLD_COMMAND: LexicalCommand = createCommand('HELLO_WORLD');\n\neditor.registerCommand(\n HELLO_WORLD_COMMAND,\n (payload: string) => {\n console.log(payload); // Hello World!\n return false;\n },\n COMMAND_PRIORITY_EDITOR,\n);\n\neditor.dispatchCommand(HELLO_WORLD_COMMAND, 'Hello World!');\n```\n\n## `editor.dispatchCommand(...)`\n\nCommands can be dispatched from anywhere you have access to the `editor` such as a Toolbar Button, an event listener, or an extension, but most of the core commands are dispatched from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\nCalling `dispatchCommand` will implicitly call `editor.update` to trigger its command listeners if it was not called from inside `editor.update`.\n\nDon't dispatch a command from inside a read-only context such as\n`editor.read(fn)` or `editorState.read(fn)`. Command listeners usually change\nthe editor, so Lexical runs them in a separate writable update and\ndevelopment builds log a warning when they detect this. Dispatch after the\nread returns instead.\n\n```js\neditor.dispatchCommand(command, payload);\n```\n\nThe `payload`s are typed via the `createCommand(...)` API, but they're usually a DOM `event` for commands dispatched from an event listener.\n\nHere are some real examples from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\n```js\neditor.dispatchCommand(KEY_ARROW_LEFT_COMMAND, event);\n// ...\neditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic');\n```\n\nAnd another example from the [`ToolbarPlugin`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) in our Playground.\n\n```js\nconst formatBulletList = () => {\n editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND);\n};\n```\n\nWhich is later handled by [`ListExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-list/src/LexicalListExtension.ts) to insert the list into the editor.\n\n```js\neditor.registerCommand(\n INSERT_UNORDERED_LIST_COMMAND,\n () => {\n $insertList('bullet');\n return true;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\n## `editor.registerCommand(...)`\n\nYou can register a command from anywhere you have access to the `editor` object, but it's important that you remember to clean up the listener with its remove listener callback when it's no longer needed.\n\nThe command listener will always be called from an `editor.update`, so you may use dollar functions. You should not use\n`editor.update` (and *never* call `editor.read(...)` or `editor.read('force-commit', ...)`) synchronously from within a command listener. It is safe to call\n`editor.read('latest', ...)` or `editor.getEditorState().read` if you need to read the previous state after updates have already been made.\n\n```js\nconst removeListener = editor.registerCommand(\n COMMAND,\n (payload) => boolean, // Return true to stop propagation.\n priority,\n);\n// ...\nremoveListener(); // Cleans up the listener.\n```\n\nThe easiest way to get clean-up right is to register commands from an\n[extension](/docs/extensions/defining-extensions)'s `register` function and\nreturn the remove callback. The editor calls it when it is disposed. To\nregister several things, combine their callbacks with `mergeRegister` from\n`@lexical/utils`.\n\n```js\nimport {LinkExtension, TOGGLE_LINK_COMMAND} from '@lexical/link';\nimport {COMMAND_PRIORITY_BEFORE_EDITOR, defineExtension} from 'lexical';\n\nexport const LinkLoggerExtension = defineExtension({\n // The command it observes is handled by LinkExtension\n dependencies: [LinkExtension],\n name: '@my-app/LinkLogger',\n register: (editor) =>\n editor.registerCommand(\n TOGGLE_LINK_COMMAND,\n (payload) => {\n console.log('link', payload);\n return false; // let the link extension handle it too\n },\n // LinkExtension handles this command at COMMAND_PRIORITY_EDITOR and\n // returns true, so observe it at the BEFORE variant of that priority.\n COMMAND_PRIORITY_BEFORE_EDITOR,\n ),\n});\n```\n\nA listener that only observes a command, like this one, needs to run before\nthe listener that handles it. Depending on the extension that handles it and\nusing the `COMMAND_PRIORITY_BEFORE_*` variant of its priority does that\nwithout escalating to a higher priority. See\n[Priorities and ordering](#priorities-and-ordering) below.\n\nIn a legacy React plugin, return the `registerCommand` call from a\n`useEffect` instead.\n\nAnd as seen above and below, `registerCommand`'s callback can return `true` to signal to the other listeners that the command has been handled and propagation will be stopped.\n\nHere's a simplified example of handling a `KEY_TAB_COMMAND` from [`TabIndentationExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-extension/src/TabIndentationExtension.ts), which is used to dispatch a `OUTDENT_CONTENT_COMMAND` or `INDENT_CONTENT_COMMAND`.\n\n```js\neditor.registerCommand(\n KEY_TAB_COMMAND,\n (payload) => {\n const event: KeyboardEvent = payload;\n event.preventDefault();\n return editor.dispatchCommand(\n event.shiftKey ? OUTDENT_CONTENT_COMMAND : INDENT_CONTENT_COMMAND,\n );\n },\n COMMAND_PRIORITY_EDITOR,\n);\n```\n\nNote that the same `KEY_TAB_COMMAND` command is registered by [`LexicalTableSelectionHelpers.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical-table/src/LexicalTableSelectionHelpers.ts), which handles moving focus to the next or previous cell within a `TableNode`, but the priority is high (`COMMAND_PRIORITY_HIGH`) because this behavior is very important.\n\n### Priorities and ordering\n\nCommand listeners are called in the following order until a listener returns `true`:\n\n- From priority highest to lowest (critical, high, normal, low, editor)\n- All `COMMAND_PRIORITY_BEFORE_${priority}` listeners, most recently registered first\n- All `COMMAND_PRIORITY_${priority}` listeners, in registration order\n\n:::note\n\nThe `COMMAND_PRIORITY_BEFORE_*` priorities make it much easier to override\ndefault behavior without escalating the priority.\n\n:::\n\nIt is best practice to use the lowest priority possible, so most commands will\nbe registered with `COMMAND_PRIORITY_EDITOR` for the default behavior, then\ncommands to override that behavior can be registered with\n`COMMAND_PRIORITY_BEFORE_EDITOR`. The higher priorities mostly serve purposes\nsuch as being able to observe-but-not-handle events and to support legacy code\nthat predates the availability of `COMMAND_PRIORITY_BEFORE_*`.\n\nA modern lexical app will typically only need the\n`COMMAND_PRIORITY_BEFORE_EDITOR` priority since the\nlast-registered-called-first ordering is suitable for almost all use cases. The\nolder priorities without BEFORE can be considered legacy and are primarily\noffered for compatibility.\n\nHere is the full ordering of priorities, from lowest to highest:\n\n- `COMMAND_PRIORITY_EDITOR`\n- `COMMAND_PRIORITY_BEFORE_EDITOR`\n- `COMMAND_PRIORITY_LOW`\n- `COMMAND_PRIORITY_BEFORE_LOW`\n- `COMMAND_PRIORITY_NORMAL`\n- `COMMAND_PRIORITY_BEFORE_NORMAL`\n- `COMMAND_PRIORITY_HIGH`\n- `COMMAND_PRIORITY_BEFORE_HIGH`\n- `COMMAND_PRIORITY_CRITICAL`\n- `COMMAND_PRIORITY_BEFORE_CRITICAL`\n","packages/lexical-website/docs/concepts/compared-with-prosemirror.md":"# Compared with ProseMirror\n\nLexical and [ProseMirror](https://prosemirror.net) are both frameworks for\nbuilding rich text editors on top of `contentEditable`, and both keep an\nimmutable document model as the source of truth. This page collects the main\ndifferences in one place, for readers who know one and are learning the other.\n\n## Document model {#document-model}\n\nLexical's tree is shaped like the HTML it renders (see\n[Document Model](./document-model.md)). This is a deliberate difference from\nProseMirror. ProseMirror's document is also a tree,\nand blocks can contain other blocks, but the inline content of a textblock is\na flat sequence of nodes (text and inline nodes) with marks for formatting and\nlinks, and every position in the document is a single integer.\n\n| | Lexical | ProseMirror |\n| -- | -- | -- |\n| Document | Immutable tree of nodes, one `RootNode` | Immutable tree of nodes, one `doc` node |\n| Node identity and navigation | Each node has a runtime key and knows its parent and siblings | Nodes are plain values with no parent links; a resolved position supplies ancestor context |\n| Blocks | `ElementNode` subclasses (paragraph, heading, list, table, …), or a block `DecoratorNode` (image, embed, …) | Block nodes defined in the schema |\n| Inline formatting | Format flags on each `TextNode` (bold, italic, code, …) | Marks on text |\n| Links and other inline wrappers | Inline `ElementNode`s (`LinkNode`, `MarkNode`) that contain text nodes | Marks on text, like formatting |\n| Embedded content | `DecoratorNode`, inline or block, rendered by your framework (for example React) | Leaf or atom nodes, often with a custom `NodeView` |\n| Several editable regions in one node | [Named slots](./named-slots.md): regions addressed by name, like a card's `title`, each isolated so editing and selection never cross the boundary | Child nodes in the order the schema's content expression allows, optionally marked `isolating`, or a separate editor inside a `NodeView` |\n| Addressing a position | Node key plus offset (`{key, offset, type}`) | One integer counted across the whole document |\n| Allowed structure | Declared by node classes, enforced with node transforms and normalization | Declared by a schema of content expressions |\n| Applying edits | Call node and selection methods inside `editor.update()` | Build a transaction from steps that address positions or ranges |\n| Rendering | Each node's `createDOM()`/`updateDOM()`, applied by the reconciler, and optionally changed per node class by a `DOMRenderExtension` override | `toDOM` in the schema, or a `NodeView` |\n\n## Serialization {#serialization}\n\nBecause a Lexical link is an element that already contains its text, it\nexports as an `` around those text nodes. A mark-based model has to find the\nadjacent text that shares a mark and group it into one element first.\n\n| Format | Lexical | ProseMirror |\n| -- | -- | -- |\n| JSON | `editorState.toJSON()`, restored with `editor.parseEditorState()` | `doc.toJSON()` and `Node.fromJSON(schema, json)` |\n| HTML export | `$generateHtmlFromNodes()`, using each node's `createDOM()` or `exportDOM()` | `DOMSerializer.fromSchema(schema)`, using `toDOM` from the schema's nodes and marks |\n| HTML import | `$generateNodesFromDOM()`, using `importDOM()` or `DOMImportExtension` rules | `DOMParser.fromSchema(schema)`, using the schema's `parseDOM` rules |\n| Markdown | `@lexical/markdown` transformers or `@lexical/mdast` | `prosemirror-markdown`: a markdown-it parser and a serializer with a function per node and mark |\n| Clipboard | Copy writes plain text, HTML, and Lexical JSON. Paste prefers the JSON, then HTML, then plain text. | Copy writes HTML and plain text. Paste parses the HTML with the schema's parse rules. |\n\nIn the JSON, a Lexical link is a `link` node with its text nodes as\n`children`, and bold is a `format` value on a `text` node, where\nProseMirror's JSON gives each text node a list of `marks`. In both editors the\ndefault HTML export reuses the definition that renders the editor\n(`createDOM()` in Lexical, `toDOM` in ProseMirror), so the two stay in step\nunless you override one. See [Serialization](../serialization/serialization.md)\nfor the details of each Lexical format.\n\n## History {#history}\n\nBoth editors group consecutive edits into one undo step. Lexical's\n[`HistoryExtension`](./history.md) merges edits made within `delay`\n(300ms by default) and keeps an unlimited stack unless you set `maxDepth`.\nProseMirror's history plugin uses `newGroupDelay: 500` and `depth: 100` by\ndefault, so `configExtension(HistoryExtension, {delay: 500, maxDepth: 100})`\nmatches its behavior.\n","packages/lexical-website/docs/concepts/document-model.md":"# Document Model\n\nAn [editor state](./editor-state.md) holds a tree of nodes. This page explains\nhow that tree is shaped.\n\n## A DOM-like tree\n\nLexical's node tree is shaped like the HTML it renders. A paragraph is an\n`ElementNode` whose children are the nodes inside it, and inline structure\nnests the same way: a link is a `LinkNode` element that contains the text\nnodes it wraps, just as an `` contains its text. Each node type decides how\nit renders with `createDOM()` and `updateDOM()`, so the model maps closely to\nthe DOM, and a position in the document is a node plus an offset within it.\n\nHere is a small document with a heading, a paragraph containing bold text and\na link, a block image, and a card that has a named `title` slot as well as\nordinary body children:\n\n```mermaid\nflowchart TB\n accTitle: The shape of a Lexical document tree\n accDescr: The root has four children in order: a heading, a paragraph, an image, and a card. The heading contains the text \"Welcome\". The paragraph contains the text \"Read the \", a bold text node \"docs\", and a link, which contains the text \"here\". The image is a block decorator node with no children. The card has a named slot called title, which holds a paragraph containing the text \"Card title\", and one ordinary child, a paragraph containing the text \"Card body\".\n root[\"Root\"] --> heading[\"Heading (h1)\"]\n root --> paragraph[\"Paragraph\"]\n root --> image[\"Image
(block DecoratorNode)\"]\n root --> card[\"Card
(ElementNode)\"]\n heading --> welcome[\"Text: 'Welcome'\"]\n paragraph --> read[\"Text: 'Read the '\"]\n paragraph --> docs[\"Text: 'docs'
{ format: bold }\"]\n paragraph --> link[\"Link\"]\n link --> here[\"Text: 'here'\"]\n card -.->|\"slot: title\"| titlePara[\"Paragraph\"]\n titlePara --> titleText[\"Text: 'Card title'\"]\n card --> body[\"Paragraph\"]\n body --> bodyText[\"Text: 'Card body'\"]\n```\n\nSolid arrows are ordinary children, which form an ordered list under their\nparent and are read with `getChildren()`. The dashed arrow is a\n[named slot](./named-slots.md): a separate channel on the host, keyed by name\ninstead of position and read with `$getSlot(card, 'title')`. A slot's value\nis the root of its own isolated region, so its `getParent()` is `null` and\n`$getSlotHost()` leads back to the card. Any `ElementNode` or `DecoratorNode`\ncan host slots, so a decorator such as the image could also expose an\neditable caption this way.\n\n## Working with the tree\n\nLexical code navigates the document the way DOM code does, with methods like\n`getParent()`, `getChildren()`, and `getNextSibling()`, and each node owns the\nDOM it renders. The resemblance is structural, not one\nnode per HTML element: bold or italic text, for example, is a format on a\n`TextNode`, not a separate `` or `` node. See\n[Nodes](./nodes.mdx) for the built-in node types.\n\n## Customizing rendering\n\nYou can also change how nodes render without subclassing them.\n[`DOMRenderExtension`](../serialization/dom-render.md) from `@lexical/html`\ntakes overrides for `createDOM`, `updateDOM`, and `exportDOM`, for one node\nclass or for every node, such as adding a `data-` attribute or wrapping a\nnode's children in another element. Each override calls `$next()` to get the\ndefault result and adjusts it, so overrides from several extensions compose.\nExport overrides only affect HTML export, and `createDOM` overrides also carry\nthrough to export for nodes that use the default `exportDOM`. Changes made\nwhile updating the editor's DOM don't; see\n[Lexical -> HTML](../serialization/serialization.md#lexical---html) for which\nhooks reach export.\n\nFor how the tree is converted to and from JSON, HTML, and Markdown, see\n[Serialization](../serialization/serialization.md#formats-at-a-glance). For\nhow this model differs from a mark-based editor, see\n[Compared with ProseMirror](./compared-with-prosemirror.md).\n","packages/lexical-website/docs/concepts/dom-events.md":"\n\n# Working with DOM Events\n\nSometimes, when working with Lexical, it might be necessary or useful for you to attach a DOM Event Listener to the underlying DOM nodes that Lexical controls. For instance, you might want to show a popover when a user mouses over a specific node or open a modal when they click on a node. Either of these use cases (and many others) can be accomplished via native DOM Event Listeners. There are 3 main ways that you can listen for DOM Events on nodes controlled by Lexical:\n\n## 1. Event Delegation\n\nOne way to handle events inside the editor is to set a listener on the editor root element (the contentEditable Lexical attaches to). You can do this using a [Root Listener](listeners.md).\n\n```js\nfunction myListener(event) {\n // You may want to filter on the event target here\n // to only include clicks on certain types of DOM Nodes.\n alert('Nice!');\n}\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) => {\n if (rootElement === null) {\n return;\n }\n // add the listener to the current root element\n rootElement.addEventListener('click', myListener);\n // remove the listener when the root element changes - make sure the ref\n // to myListener is stable so the removal works and you avoid a memory leak.\n return () => rootElement.removeEventListener('click', myListener);\n }),\n});\n```\n\nAn extension's `register` returns a cleanup function, and the editor calls it\nwhen it is disposed, so there is no teardown to write by hand. Add\n`ClickExtension` to your editor's `dependencies` to use it.\nThis can be a simple, efficient way to handle some use cases, since it's not necessary to attach a listener to each DOM node individually.\n\nThe `addEventListener`/`removeEventListener` pairing above is common enough that the core `lexical` package exports a `registerEventListener(target, type, listener, options?)` helper. It attaches the listener and returns a dispose function that removes it, so the example above becomes:\n\n```js\nimport {defineExtension, registerEventListener} from 'lexical';\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) =>\n // registerEventListener returns the matching removeEventListener cleanup,\n // so there's no need to write the teardown by hand.\n rootElement === null\n ? undefined\n : registerEventListener(rootElement, 'click', myListener),\n ),\n});\n```\n\nIt mirrors the `addEventListener` overloads (so the event type is strongly typed) and composes well with `mergeRegister` when you need to register several listeners at once.\n\nTo attach several listeners to the same target, `registerEventListeners(target, listeners, options?)` takes a `{type: listener}` map and returns a single dispose function that removes all of them. Each listener's event argument is still strongly typed per event type, and the optional `options` argument is shared across every listener:\n\n```js\nimport {registerEventListeners} from 'lexical';\n\nconst removeListeners = registerEventListeners(\n rootElement,\n {\n click: onClick,\n keydown: onKeyDown, // receives a KeyboardEvent\n },\n {capture: true}, // shared by both listeners\n);\n```\n\nBecause `options` is shared, register a group that needs different options (such as a different `capture` flag) with a separate `registerEventListeners` call and combine the results with `mergeRegister`.\n\n## 2. Directly Attach Handlers\n\nIn some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that your handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](listeners.md).\n\n```js\nconst registeredElements: WeakSet = new WeakSet();\nconst removeMutationListener = editor.registerMutationListener(nodeType, (mutations) => {\n editor.getEditorState().read(() => {\n for (const [key, mutation] of mutations) {\n const element: null | HTMLElement = editor.getElementByKey(key);\n if (\n // Updated might be a move, so that might mean a new DOM element\n // is created. In this case, we need to add an event listener too.\n (mutation === 'created' || mutation === 'updated') &&\n element !== null &&\n !registeredElements.has(element)\n ) {\n registeredElements.add(element);\n element.addEventListener('click', (event: Event) => {\n alert('Nice!');\n });\n }\n }\n });\n});\n\n// teardown the listener - return it from an extension's `register` so the\n// editor removes it when it is disposed.\nremoveMutationListener();\n```\nNotice that here we don't worry about cleaning up, as Lexical will dereference the underlying DOM nodes and allow the JavaScript runtime garbage collector to clean up their listeners.\n\n## 3. Use NodeEventPlugin\n\nIf you're using React, we've wrapped approach #2 up into a simple React plugin that you can render inside your composer to achieve the same effect, without worrying about the details:\n\n```jsx\n\n {\n alert('Nice!');\n }}\n />\n\n```\n\nIf the editor lives inside a shadow root or an iframe, see\n[Shadow DOM and iframes](./shadow-dom.md) for the helper to read\n`event.target` through the shadow boundary — the browser retargets it to the\nshadow host on listeners attached above the boundary, so a plain\n`event.target` won't match a node inside the editor.\n","packages/lexical-website/docs/concepts/editor-state.md":"\n\n# Editor State\n\n## Why is it necessary?\n\nWith Lexical, the source of truth is not the DOM, but rather an underlying state model\nthat Lexical maintains and associates with an editor instance.\n\nWhile HTML is great for storing rich text content it's often \"way too flexible\" when it comes to text editing.\nFor example the following lines of content will produce equal outcome:\n\n```html\nLexical\nLexical\nLexical\n```\n\n
\n See rendered version!\n
\n Lexical\n Lexical\n Lexical\n
\n
\n\nOf course, there are ways to normalize all these variants to a single canonical form, however this would require DOM manipulation and so re-rendering of the content. And to overcome this we can use Virtual DOM, or State.\n\nOn top of that it allows to decouple content structure from content formatting. Let's look at this example stored in HTML:\n\n```html\n

Why did the JavaScript developer go to the bar? Because he couldn't handle his Promises

\n```\n\n
\n \"Nested\n
Nested structure of the HTML state because of the formatting
\n
\n\nIn contrast, Lexical decouples structure from formatting by offsetting this information to attributes. This allows us to have canonical document structure regardless of the order in which different styles were applied.\n\nHere is the same content as a Lexical node tree, printed the way the\n[tree view](/docs/getting-started/devtools) shows it (the numbers are node keys):\n\n```text\nroot\n └ (2) paragraph\n ├ (3) text \"Why did the JavaScript developer go to the bar? \"\n ├ (4) text \"Because he couldn't handle his \" { format: bold }\n ├ (5) text \"Promise\" { format: bold, italic }\n └ (6) text \"s\" { format: bold }\n```\n\nThe paragraph's children are a flat list of text nodes, and the formatting is a\nproperty of each one, so there is only one way to represent this content.\n\n## Understanding the Editor State\n\nYou can get the latest editor state from an editor by calling `editor.getEditorState()`.\n\nEditor states have two phases:\n\n- During an update they can be thought of as \"mutable\". See \"Updating state\" below to\n mutate an editor state.\n- After an update, the editor state is then locked and deemed immutable from there on. This\n editor state can therefore be thought of as a \"snapshot\".\n\nEditor states contain two core things:\n\n- The editor node tree (starting from the root node). See\n [Document Model](./document-model.md) for how the tree is shaped.\n- The editor [selection](./selection.md) (which can be null).\n\nFor example, \"Hello world\" with a link around \"world\" and the caret at the\nend looks like this:\n\n```mermaid\nflowchart TB\n accTitle: A simple editor state\n accDescr: The root contains a paragraph with a \"Hello \" text node and a link. The link contains the \"world\" text node. The selection's anchor and focus both point to offset 5 in \"world\".\n subgraph state[\"EditorState\"]\n direction TB\n root[\"Root\"] --> paragraph[\"Paragraph\"]\n paragraph --> hello[\"Text: 'Hello '\"]\n paragraph --> link[\"Link\"]\n link --> world[\"Text: 'world'\"]\n selection[\"Selection\"] -.->|\"caret at offset 5\"| world\n end\n```\n\n`editor.getEditorState()` returns the latest committed state. Its `toJSON()`\nmethod serializes the document tree only; the selection and the runtime node\nkeys are not included. To restore saved content, pass the JSON to\n`editor.parseEditorState()` and the result to `editor.setEditorState()`. The\neditor must have the same node types registered. See\n[Serialization](../serialization/serialization.md) for JSON, HTML, and\nMarkdown.\n\nHere's an example of how you can initialize an editor with saved content and\nthen persist it. The saved JSON is passed as the editor's `$initialEditorState`:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\n// Get the saved content (e.g. loaded from a backend)\nconst initialEditorState = await loadContent();\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n);\neditor.setRootElement(document.getElementById('editor'));\n\n// Store the content (e.g. when the user submits a form)\nasync function onSubmit() {\n await saveContent(JSON.stringify(editor.getEditorState()));\n}\n```\n\nWith React, pass the extension to `LexicalExtensionComposer`. A component\nrendered inside it can reach the editor with `useLexicalComposerContext()`:\n\n```jsx\nimport {LexicalExtensionComposer} from '@lexical/react/LexicalExtensionComposer';\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\nimport {useMemo} from 'react';\n\nfunction SaveButton() {\n const [editor] = useLexicalComposerContext();\n return (\n saveContent(JSON.stringify(editor.getEditorState()))}>\n Save\n \n );\n}\n\nfunction Editor({initialEditorState}) {\n // The editor is recreated whenever this extension changes,\n // so keep it stable for the life of the editor.\n const extension = useMemo(\n () =>\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n [initialEditorState],\n );\n return (\n \n \n \n );\n}\n```\n\n`$initialEditorState` is applied once, when the editor is built; changing it\nlater has no effect on that editor. See \"Updating state\" below for the proper\nway to change editor state after initialization.\n\n`$initialEditorState` accepts:\n\n- a JSON string or a parsed `SerializedEditorState` object, passed to\n `editor.parseEditorState()` (as in the example above);\n- an `EditorState` instance, applied directly with `editor.setEditorState()`;\n- a function `(editor) => void`, run inside `editor.update(...)`;\n- `null`, which skips default initialization entirely. Use this with\n [collaboration](/docs/collaboration/react) so that the Yjs document, not\n Lexical, owns the initial state.\n\nOmitting the field (or passing `undefined`) seeds the root with a default empty\n`ParagraphNode`. The two are not interchangeable: `null` leaves the root with no children,\nwhile `undefined` produces a single empty line. If your `loadContent` may yield `null` or\n`undefined` for new documents, coalesce to `undefined` (e.g. `(await loadContent()) ?? undefined`)\nso the editor still gets the default paragraph rather than the collab-style uninitialized\nstate.\n\nThe legacy `LexicalComposer` takes the same values as `initialConfig.editorState`,\nexcept that a function there only runs if the root is still empty.\n\n## Updating state\n\nAll reads and writes of the document happen inside a synchronous callback:\n\n```js\nimport {$createParagraphNode, $createTextNode, $getRoot} from 'lexical';\n\neditor.update(() => {\n const paragraph = $createParagraphNode();\n paragraph.append($createTextNode('Hello world'));\n $getRoot().append(paragraph);\n});\n\nconst text = editor.read('force-commit', () => $getRoot().getTextContent());\n```\n\n### The `$` function convention {#dollar-functions}\n\nFunctions whose names start with `$`, such as `$getRoot()` and\n`$getSelection()`, only work inside one of these callbacks, because they act\non the active editor state. Calling them anywhere else throws an error. The\nconvention is similar to React Hooks:\n\n| | React Hooks | Lexical `$` functions |\n| -- | -- | -- |\n| Naming | `useFunction` | `$function` |\n| Can only be called | while rendering a component | inside an update or read |\n| Can call others of the same kind | ✅ | ✅ |\n| Must be synchronous | ✅ | ✅ |\n| Must be called unconditionally, in the same order | ✅ | ❌ No such rule |\n\nCommand handlers and node transforms already run inside an update, so they\ncan call `$` functions directly.\n\nThis works because, while a callback runs, Lexical keeps the active editor and\nthe active editor state in module-level variables, and `$` functions read\nthem: `$getRoot()` returns the root of the active state, and `$getEditor()`\nreturns the active editor. Because the callback is synchronous, nothing else\ncan run in between and change them. The same mechanism enforces the\ndifference between reads and updates. Inside a read, a method that would\nchange a node throws `Cannot use method in read-only mode.`\n\nGive your own functions a `$` prefix when they call `$` functions, so it is\nclear where they can be used. The\n[`@lexical/rules-of-lexical`](/docs/packages/lexical-eslint-plugin) ESLint rule\nchecks this convention.\n\nThe same rule applies to node objects. Call node methods only inside a read or\nupdate. Every node has a key that identifies it across versions of the editor\nstate, and node methods use that key to find the latest version of the node.\nThis is why a node reference taken earlier in an update stays usable after the\nnode changes. Keys exist only at runtime: they are not serialized, and you\nshould treat them as opaque.\n\nBecause the callbacks are synchronous, do any asynchronous work (fetching\ndata, awaiting a promise) first, and then enter an update with the result.\n\nAvoid nesting one `editor.update()` inside another: the inner update does not\nrun immediately but is queued to run after the outer one. Never start an\nupdate inside a read.\n\nEach update works on a pending copy of the editor state, and updates made in\nthe same tick are committed and reconciled to the DOM together. See\n[Updates](./updates.mdx#update-lifecycle) for the full lifecycle.\n\n### Replacing the state\n\nAnother way to set state is `setEditorState` method, which replaces current state with the one passed as an argument.\n\nHere's an example of how you can set editor state from a stringified JSON:\n\n```js\nconst editorState = editor.parseEditorState(editorStateJSONString);\neditor.setEditorState(editorState);\n```\n\n:::warning\n\n`setEditorState` rejects an `EditorState` that satisfies `editorState.isEmpty()` — i.e.\nthe root is the only node and there is no selection. In a development build it throws\n`\"setEditorState: the editor state is empty. Ensure the editor state's root node never\nbecomes empty.\"`; in production it warns with the same message and recovers by appending\nan empty `ParagraphNode`, so the editor stays usable. The `EditorState` produced by\ninitializing with `editorState: null` and never appending content (typical for a\ncollaboration document before peers connect) has exactly this shape, so persisting and\nreloading such a state hits this path. Note that `parseEditorState` itself succeeds — the\ncheck lands on the apply step. To avoid relying on the recovery, guard with\n`editorState.isEmpty()` before calling `setEditorState`, or seed the document with a\n`ParagraphNode` before serializing.\n\n:::\n\n## Reading state\n\nWhich state you see depends on how you read it:\n\n- Inside `editor.update()` you see the **pending** state, where your changes\n are visible but transforms and reconciliation may not have run yet.\n `editor.read('pending', fn)` gives you the same view without allowing\n changes.\n- `editor.read('force-commit', fn)` first commits any pending updates, so it\n always sees a consistent, reconciled state. Do not call it inside an update.\n `editor.read(fn)` with no mode does the same thing, and is kept for\n convenience and backwards compatibility. Inside a mutation or update\n listener it does not commit an update that another listener started (that\n update commits after the listeners have run, so they observe commits in\n order); use `editor.read('latest', fn)` there.\n- `editor.read('latest', fn)` reads the most recently reconciled state without\n committing anything, so pending changes are not visible.\n- `editorState.read(fn, {editor})` reads one particular snapshot, such as the\n `editorState` an update listener receives. Passing the `editor` keeps\n `$getEditor()` and extension lookups working inside the callback.\n\n## State update listener\n\nIf you want to know when the editor updates so you can react to the changes, you can add an update\nlistener to the editor, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(\n () => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n },\n // Passing the editor keeps $getEditor() and extension lookups working.\n {editor},\n );\n});\n```\n\n## When are Listeners, Transforms, and Commands called?\n\nThere are several types of callbacks that can be registered with the editor that are related to\nupdates of the Editor State.\n\n| Callback Type | When It's Called |\n| -- | -- |\n| Update Listener | After reconciliation |\n| Mutation Listener | After reconciliation |\n| Node Transform | During `editor.update()`, after the callback finishes, if any instances of the node type they are registered for were updated |\n| Command | As soon as the command is dispatched to the editor (called from an implicit `editor.update()`) |\n\n## Synchronous reconciliation with discrete updates\n\nWhile commit scheduling and batching are normally what we want, they can sometimes get in the way.\n\nConsider this example: you're trying to manipulate an editor state in a server context and then persist it in a database.\n\n```js\neditor.update(() => {\n // manipulate the state...\n});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\nThis code will not work as expected, because the `saveToDatabase` call will happen before the state has been committed.\nThe state that will be saved will be the same one that existed before the update.\n\nFortunately, the `discrete` option for `LexicalEditor.update` forces an update to be immediately committed.\n\n```js\neditor.update(() => {\n // manipulate the state...\n}, {discrete: true});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\n### Cloning state\n\nLexical state can be cloned, optionally with custom selection. One of the scenarios where you'd want to do it\nis setting editor's state but not forcing any selection:\n\n```js\n// Passing `null` as a selection value to prevent focusing the editor\neditor.setEditorState(editorState.clone(null));\n```\n","packages/lexical-website/docs/concepts/headless.md":"# Running Without a Browser\n\nThe DOM is only needed to show an editor on screen. Because every read and\nupdate goes through the editor state, Lexical also works where there is no\nbrowser DOM:\n\n- **With no DOM at all.** An editor that has no root element skips\n reconciliation and DOM selection entirely, so you can build one with\n `buildEditorFromExtensions()` and never call `setRootElement()`. Adding\n `HeadlessExtension` from `@lexical/headless` makes that explicit: attaching a\n root element then throws, and nested editors are headless too. Updates,\n transforms, listeners, commands, and JSON serialization all still work,\n which is enough to process documents on a server, apply changes from a\n collaboration backend, or write tests.\n- **With a virtual DOM** such as happy-dom or jsdom, for the features that\n create DOM nodes, like HTML import and export. `withDOM()` from\n `@lexical/headless/dom` runs a callback with a temporary happy-dom window,\n for example to convert HTML on a server.\n\n## Example: converting saved JSON to HTML on a server\n\n```ts\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {HeadlessExtension} from '@lexical/headless';\nimport {withDOM} from '@lexical/headless/dom';\nimport {$generateHtmlFromNodes} from '@lexical/html';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [HeadlessExtension, RichTextExtension],\n name: '@my-app/server-editor',\n }),\n);\n\nexport function jsonToHtml(json: string): string {\n editor.setEditorState(editor.parseEditorState(json));\n return withDOM(() => editor.read(() => $generateHtmlFromNodes(editor)));\n}\n```\n\nThe editor must have the same node types registered as the editor that saved\nthe JSON, which is why it uses the same extensions. JSON and Markdown\nconversion do not need `withDOM()`.\n\n## `createHeadlessEditor()`\n\nBefore extensions, headless editors were created with `createHeadlessEditor()`\nfrom `@lexical/headless`. It still works, and it makes DOM-only methods such as\n`registerRootListener` and `registerMutationListener` throw. Because many\nextensions register those listeners, use `HeadlessExtension` with\n`buildEditorFromExtensions()` in new code.\n","packages/lexical-website/docs/concepts/history.md":"# History\n\nLexical adds support for Undo and Redo through the `@lexical/history` package —\n`registerHistory`, the `HistoryExtension` extension, or the `HistoryPlugin`\nReact component from `@lexical/react/LexicalHistoryPlugin`. Part of undo and redo requires supporting coalescing of certain dynamic operations such as continuous typing. The below provides background information regarding the continuous typing undo coalescing feature.\n\n**Undo Coalescing of Typed Text**\n\n**TL;DR**\nWhen working with text editors, users expect a well polished undo experience. A key part of this is a smooth, well thought out workflow when undoing continuous typing events. For this post, strict typing events may be limited to typing characters, backspacing and forward deleting. Users generally expect that continuous typing should fully undo with a single undo gesture and that they don’t require separate undo gestures for each character.\nThe algorithm that covers this is “undo coalescing of typed text” and there’s a certain degree of nuance involved. This post covers that nuance while attempting to avoid prescriptive implementation details.\n\n**What Kind of Edits Require Coalescing?**\nAs mentioned above, continuous typing should be coalesced into a single undo action. Continuous typing is a loaded phrase and we’ll get into some details below.\nThere are other types of edits that require undo coalescing such as rapidly resizing an image or rapidly changing the font size of selected text. These latter two examples fall under what might be termed “dynamic operations” and their implementation might vary quite a bit from coalescing of typing.\n\n**What Constitutes Continuous Typing?**\nFor the purposes of undo coalescing, continuous typing events are safely limited to these three actions:\n\n1. Forward typing characters (heads up, composed character typing discussed later).\n2. Deleting backwards, e.g. backspace gestures including backspace key presses.\n3. Forward deletion, e.g. forward delete gestures including Delete key presses.\n\nAny interruption to the above breaks the notion of continuous typing. Note that switching between either of these three actions may itself be considered an interruption of continuous typing or it may not. This ends up being a usability decision. In my opinion, when examining various word processors, switching between these three actions should maintain continuity, because users often make typos or corrections in the flow of typing and therefore would lean towards the whole sequence of typing, backspacing and deleting to be within a single undoable session.\nNote that Google Docs and Quip treat a switch between typing, backspacing and deleting as disruptions to the continuous typing sessions.\n\n**Start with Selected Text and Followup with Typing**\nLet’s start with some selected text. The user may have selected the text directly, as a result of pasting text or through some other sequence of steps. When followed by continuous typing, the initial selection should be included along with the following typing events as part of a single coalesced undo session.\n\n**Timeouts**\nText editing is generally a modeless user experience and so just about any event beyond the above typing actions will disrupt continuous typing. The first and foremost is a timeout.\nQuip seems to require continuous typing to occur within 1 second intervals, whereas Google Docs requires about 2 seconds. In my opinion, the timeout may stretch to as long as 3 to 5 seconds. The more time between typing events, the more chance the user has to intentionally input a block of text, a thought or concept.\nThe use of a timeout is not necessarily required, and the amount of time is certainly up for debate. Collaborative co-editing also makes use of timeouts when grouping text that is merged across clients. Longer timeouts tend to make collaboration a smoother, less disruptive experience, because receiving other client input while expressing one’s thoughts tends to be unhelpful.\nImplementers should consider the correct timeout based on their customer expectations and related collaborative features that might share this timeout.\n\n**Hard and Soft Returns**\nHard returns as generated by pressing the Return key tend to disrupt and thereby reset continuous typing.\nFor Google Docs and Quip, soft returns as generated by pressing shift+Return key do not terminate continuous typing. This makes sense in that the soft return ends text wrap but does not end the paragraph.\n\n**Changing Selections and Key Focus**\nAny change to the selection by the user should terminate coalescing. This includes:\n\n- Arrow gesture navigation.\n- Gestures to select a word, a sentence or a paragraph.\n- Any other selection change that does not move the blinking caret to the next or previous character by way of the above mentioned typing events.\n\nAdditionally, ending keyboard focus on the editing window, including moving focus to another editing window or a different view within the same window should also terminate coalescing. This also includes setting focus to modal popovers, such as, for example, a hyperlink property editor.\n\n**Composed Characters**\nCharacter composition occurs when typing diacritics, CJK and even emojis. The process usually involves at least these three phases:\n\n- Start composition.\n- Replace composed text with other text and remain composing. This step may occur many times within a single composition session.\n- Stop composition either through accepting the text or canceling the latest input.\n\nCoalescing should terminate at start composition. Replacing composed text should generally be coalesced. Stopping composition may or may not reset coalescing depending upon the implementation. Quip appears to try to coalesce multiple composed characters, but disrupts coalescing when switching between composed and non-composed characters. Google Docs appears to disrupt coalescing more frequently. Both coalesce the text replacements.\n\n**Auto Correct, Spelling Corrections and Text Substitutions**\nText substitution behaves much like composed characters. When the text is transformed, the coalescing should terminate and the transformed text becomes the first coalesced entry in the next undo session.\n\n**Copy & Pasting**\nAny actions like copy and paste typically trigger events that are not part of the 3 continuous typing actions described above. So, copy and paste also terminates coalescing.\n\n**In Conclusion**\nText undo coalescing greatly improves the usability of undo in that it allows the user to bypass all the intermediate events that went into forming or re-forming text within a paragraph. Given the modeless nature of text editing, limiting continuous typing to strictly three events allows for a robust and clean implementation. Implementers will need tight bottlenecks to trap selection changes, key focus changes as well as changes from collaborative clients. While the above is not complete by any means, I hope readers will find it helpful.\n\n## Tuning HistoryExtension for memory and long sessions\n\n`HistoryExtension` ships with config values chosen for the common case\nof a short-lived editor on a richly interactive surface. For\napplications that keep an editor mounted for a long time — chat\nthreads, long documents, anything where the user may produce thousands\nof distinct history events without reloading the page — two settings\nare worth tuning explicitly.\n\n### `maxDepth` — cap the undo stack\n\nBy default `maxDepth` is `null`, meaning the undo stack is\n**unbounded**. Every separate-history boundary (see \"What Constitutes\nContinuous Typing?\" above) pushes a `HistoryStateEntry` that retains a\nfull `EditorState` snapshot. Snapshots share a copy-on-write\n`NodeMap`, so the marginal cost of any one entry is small, but it is\nnot zero — and an unbounded stack accumulates a long tail over time.\n\nSet a finite `maxDepth` to keep the stack at a fixed length. The\nextension FIFO-evicts the oldest entries past the cap; older snapshots\nbecome unreachable and can be collected.\n\n```ts\nimport {configExtension, defineExtension} from 'lexical';\nimport {HistoryExtension} from '@lexical/history';\n\nconst editorExtension = defineExtension({\n // ...\n dependencies: [\n // 100 events is a reasonable starting point that supports a deep\n // enough undo stack for almost any interactive editing session.\n configExtension(HistoryExtension, {maxDepth: 100}),\n ],\n});\n```\n\nThe cap is also exposed as a writable signal on\n`HistoryExtension.output.maxDepth`, so it can be reconfigured at\nruntime (the new value applies to future pushes — the current stack\nis not retroactively trimmed when the cap is lowered).\n\n### `delay` — coalesce more aggressively\n\n`delay` is the merge window during which adjacent edits collapse into\nthe current history entry instead of pushing a new one. The default is\n`300`ms. A longer delay means fewer history events for the same\ntyping burst, which:\n\n- reduces the rate at which `undoStack` grows, multiplying the effect\n of any `maxDepth` cap, and\n- gives the user undo gestures that match larger semantic chunks of\n their writing.\n\nFor text-heavy editors a value in the `500`–`1000`ms range is common.\n\n```ts\nconfigExtension(HistoryExtension, {delay: 500, maxDepth: 100}),\n```\n\n### When NOT to cap history\n\nIf your editor is short-lived (mounted only for the duration of a\nmodal, page form, or single message draft) and undo is expected to\nreach back to the document's initial state, the default `maxDepth:\nnull` is fine — the stack will be discarded with the editor instance.\nThe cap matters when an editor is **long-lived** and can accumulate\nthousands of distinct history events without unmounting.\n","packages/lexical-website/docs/concepts/key-management.md":"# Key Management\n\nKeys are a fundamental concept in Lexical that enable efficient state management and node tracking. Understanding how keys work is crucial for building reliable editor implementations.\n\n## What are Keys?\n\nThe `__key` property is a unique identifier assigned to each node in the Lexical editor. These keys are:\n- Automatically generated by Lexical\n- Used to track nodes in the editor state\n- Essential for state management and updates\n- Immutable during a node's lifecycle\n\n## When to Use `__key`?\n\n### ✅ Correct Usage\n\nKeys should ONLY be used in two specific situations:\n\n1. **In Node Constructors**\n```typescript\nclass MyCustomNode extends ElementNode {\n constructor(someData: string, key?: NodeKey) {\n super(key); // Correctly passing key to parent constructor\n this.__someData = someData;\n }\n}\n```\n\n2. **In Static Clone Methods**\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### ❌ Incorrect Usage\n\nNever use keys in these situations:\n\n```typescript\n// ❌ Don't pass keys between different nodes\nconst newNode = new MyCustomNode(existingNode.__key);\n\n// ❌ Don't manipulate keys directly\nnode.__key = 'custom-key';\n```\n\n## How Lexical Uses Keys\n\n### Diagram\n\nThe dotted outlines show nodes that are re-used in a zero-copy fashion from one EditorState to the next\n\n```mermaid\ngraph TB\n subgraph s0[\"Initial State\"]\n direction TB\n m0[\"NodeMap (v0)\"]\n m0 -->|Key A| n0a[\"A (v0)\"]\n m0 -->|Key B| n0b[\"B (v0)\"]\n end\n subgraph s1[\"Create Node C\"]\n direction TB\n style n1a stroke-dasharray: 5 5\n style n1b stroke-dasharray: 5 5\n m1[\"NodeMap (v1)\"]\n m1 -->|Key A| n1a[\"A (v0)\"]\n m1 -->|Key B| n1b[\"B (v0)\"]\n m1 -->|Key C| n1c[\"C (v0)\"]\n end\n subgraph s2[\"Update Node A\"]\n direction TB\n style n2a stroke-dasharray: 5 0\n style n2b stroke-dasharray: 5 5\n style n2c stroke-dasharray: 5 5\n m2[\"NodeMap (v1)\"]\n m2 -->|Key A| n2a[\"A (v1)\"]\n m2 -->|Key B| n2b[\"B (v0)\"]\n m2 -->|Key C| n2c[\"C (v0)\"]\n end\n s0 -.-> s1 -.-> s2\n```\n\n### Node Map Structure\n\nThe EditorState maintains a `Map` that tracks all nodes. Nodes refer to each other using keys in their internal pointers:\n\n```typescript\n// Internal node structure (not for direct usage)\n{\n __prev: null | NodeKey,\n __next: null | NodeKey,\n __parent: null | NodeKey,\n // __first, __last and __size are only for ElementNode to track its children\n __first: null | NodeKey,\n __last: null | NodeKey,\n __size: number\n}\n```\n\nThese internal pointers maintain the tree structure and should never be manipulated directly.\n\n### Key-Related APIs\n\n1. **Editor Methods**\n ```typescript\n // Get node by key\n const node = $getNodeByKey(key);\n\n // Get the DOM element a node key is reconciled to\n const element = editor.getElementByKey(key);\n\n // Get latest version of a node\n const latest = node.getLatest();\n \n // Get mutable version for updates\n const mutable = node.getWritable();\n ```\n\n### Key Lifecycle\n\nNodeKeys are ephemeral and have several important characteristics:\n\n1. **Serialization**\n - Keys are never serialized\n - New keys are generated when deserializing (from JSON/HTML)\n - Keys are only meaningful within their EditorState instance\n\n2. **Uniqueness**\n - Keys are unique within an EditorState\n - Current implementation uses serial numbers for debugging\n - Should be treated as random and opaque values\n - Never logically reused\n\nKeys are used internally by Lexical to:\n1. Track nodes in the editor state\n2. Manage node updates and versions\n3. Maintain referential integrity\n4. Enable efficient state updates\n\n## Common Pitfalls\n\n1. **Key Reuse**\n ```typescript\n // ❌ Never do this\n function duplicateNode(node: LexicalNode) {\n return new SameNodeType(data, node.__key);\n }\n ```\n\n2. **Manual Key Assignment**\n ```typescript\n // ❌ Never do this\n node.__key = generateCustomKey();\n ```\n\n3. **Incorrect Constructor/Clone Implementation**\n ```typescript\n // ❌ Never do this - missing key in constructor\n class MyCustomNode extends ElementNode {\n constructor(someData: string) {\n super(); // Missing key parameter\n this.__someData = someData;\n }\n }\n\n // ✅ Correct implementation\n class MyCustomNode extends ElementNode {\n __someData: string;\n\n constructor(someData: string, key?: NodeKey) {\n super(key);\n this.__someData = someData;\n }\n \n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__someData = prevNode.__someData;\n }\n }\n ```\n\n4. **Node Replacement**\n ```typescript\n // ❌ Never re-use the key when changing the node class\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(node.__key),\n withKlass: CustomNodeType\n }\n ]\n };\n\n // ✅ Correct: Use node replacement configuration\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(),\n withKlass: CustomNodeType\n }\n ]\n };\n ```\n\n For proper node replacement, see the [Node Replacement guide](node-replacement.md).\n\n## Best Practices\n\n1. **Let Lexical Handle Keys**\n ```typescript\n import {$applyNodeReplacement} from 'lexical';\n\n // Create node helper function\n export function $createMyCustomNode(data: string): MyCustomNode {\n return $applyNodeReplacement(new MyCustomNode(data));\n }\n ```\n\n## Testing Considerations\n\nWhen writing tests involving node keys:\n\n```typescript\ntest('node creation', async () => {\n await editor.update(() => {\n // ✅ Correct: Create nodes normally\n const node = new MyCustomNode(\"test\");\n \n // ✅ Correct: Keys are automatically handled\n expect(node.__key).toBeDefined();\n expect(node.__key).not.toBe('');\n });\n});\n```\n\n## Performance Impact\n\nUnderstanding key management is crucial for performance:\n\n1. Keys enable efficient node lookup (O(1))\n2. Proper key usage prevents unnecessary re-renders\n3. Lexical's key system optimizes state updates\n4. Improper key manipulation can cause performance issues\n\n## Common Questions\n\n**Q: How do I reference a node later?**\nA: Store a reference to the node. Conventionally, all node methods will use `getLatest()` or `getWritable()` which will look up the latest version of that node before reading or writing its properties, which is equivalent to using the key but is type-safe (but may cause errors if you try to use a reference to a node that no longer exists). In some situations it may be preferable to use the key directly, which is also fine.\n\n**Q: How do I ensure unique nodes?**\nA: Let Lexical handle key generation and management. Focus on node content and structure. ","packages/lexical-website/docs/concepts/keyboard-accessibility.md":"# Keyboard Accessibility\n\nLexical follows the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) keyboard model. This page documents the contracts that plugin authors and host applications rely on, so a Lexical editor can sit inside a larger keyboard-accessible flow without trapping or surprising the user.\n\n## Tab key\n\nBy default, `Tab` inside the editor follows the browser's normal focus order — it moves to the next focusable element on the page. There is no keyboard trap.\n\nThe optional `TabIndentationExtension` (`@lexical/extension`) takes over `Tab` and uses it for block indent / outdent. Hosts that mount this extension opt in to that behavior. WCAG 2.1.2 (No Keyboard Trap) still applies — pressing `Escape` blurs the editor (see below), at which point `Tab` leaves the editor again.\n\n## Escape key\n\nPressing `Escape` while the editor has focus calls `editor.blur()` via the rich-text Escape command handler (registered at `COMMAND_PRIORITY_EDITOR`). The handler only blurs when the current selection is a range selection; with a `NodeSelection` (or no selection) it returns `false` and falls through without blurring. After blur, the next `Tab` advances to the page's next focusable element — so the editor is not a hard keyboard trap. (`TabIndentationExtension` consumes `Tab` only while a range selection is active, and its own source notes that taking over `Tab` is generally discouraged for keyboard accessibility, so treat WCAG 2.1.2 conformance as something to verify in your integration rather than a guarantee.)\n\nPlugin authors who want to intercept `Escape` (modal close, dropdown close, etc.) should register their handler at a higher priority and return `true` to stop the command chain. Common patterns already established in the codebase:\n\n| Priority | Caller | Purpose |\n| --- | --- | --- |\n| `HIGH` | Floating link editor | Close the floating UI, keep editor focus |\n| `HIGH` | Equation component (while editing) | Close the equation editor input |\n| `NORMAL` | Comment plugin | Cancel inline comment editing |\n| `LOW` | Image component | Escape out of caption / resize editing: drop the inner selection and restore the `NodeSelection` on the image decorator |\n| `EDITOR` | Rich text (default) | `editor.blur()` (range selection only) |\n\nHandlers that return `false` let the chain continue, so Escape can still fall through to the default blur even after a higher-priority handler runs.\n\nSome host UI binds its close handler directly to a DOM `keydown` listener rather than going through `KEY_ESCAPE_COMMAND` — the playground's `Modal` via `window.addEventListener('keydown', ...)` and its `DropDown` via a React `onKeyDown` on the menu. Those paths run alongside the table above; they do not participate in the editor's command priority chain.\n\n## React hooks and `@lexical/a11y` extensions\n\nThe keyboard helpers below ship as `@lexical/a11y` _extensions_ — the extension is the API and does all of the work (event listeners, focus management, the live region). The `@lexical/react` hooks (`useLexicalFocusManagerRef`, `useLexicalRovingTabIndexRef`, `useLexicalFocusTrapRef`, `useLexicalAriaLiveRegion`) are thin React adapters that only _communicate_ with their extension: each returns a `RefCallback` (or an `announce` function) that drives the extension's signals. Using a hook therefore **requires** its matching extension to be registered in the editor's extension tree — it is not an optional integration path. Non-React hosts (Svelte, Vue, vanilla DOM) use the extensions directly and skip the hooks.\n\n## Toolbar focus jump\n\nThe playground uses `useLexicalFocusManagerRef` (`@lexical/react/useLexicalFocusManagerRef`) to provide a documented shortcut for moving focus from the editor to the toolbar without tabbing through the page. The hook returns a `RefCallback` that registers the attached element as a focus-managed toolbar. It listens for `Alt+F10` inside the editor and moves focus into the toolbar — preferring the item that currently carries `tabindex=\"0\"` (the active roving item, when paired with `useLexicalRovingTabIndexRef`), and otherwise the first focusable item. While focus is in the toolbar, pressing `Escape` restores both focus and the editor's prior selection via `editor.focus()`. Multiple toolbars can be registered simultaneously. Requires `FocusManagerExtension` from `@lexical/a11y` in the editor's extension tree.\n\nThis matches the WAI-ARIA editor menubar pattern and the convention used by Word and CKEditor. Hosts that don't mount `useLexicalFocusManagerRef` get the default browser flow (Tab in, Tab out).\n\n## Toolbar arrow-key navigation\n\nToolbars that opt into `useLexicalRovingTabIndexRef` (`@lexical/react/useLexicalRovingTabIndexRef`) collapse to a single tab stop: arrow keys move between items inside the toolbar; `Tab` moves past the toolbar as a whole. Items keep `tabindex=\"-1\"` except the active one (`tabindex=\"0\"`). The hook returns a `RefCallback` — multiple containers can be registered simultaneously. Tracks the WAI-ARIA toolbar pattern. Requires `RovingTabIndexExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Modal focus trap\n\n`useLexicalFocusTrapRef` (`@lexical/react/useLexicalFocusTrapRef`) returns a `RefCallback` that cycles `Tab` / `Shift+Tab` inside a modal container and restores focus to the previously-focused element on deactivation. While active, the trap also installs a document-level `focusin` listener that pulls any focus landing outside the container back to the first focusable descendant (or the container itself) — so it recovers from the browser routing `Tab` out to its own chrome. Although several containers can be _registered_, only one trap should be _active_ at a time: concurrent traps install competing `focusin` listeners and fight over focus. Escape is **not** intercepted by the hook — modal owners handle the close key themselves, so the editor's Escape contract above stays predictable. Requires `FocusTrapExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Screen reader announcements\n\n`useLexicalAriaLiveRegion` (`@lexical/react/useLexicalAriaLiveRegion`) returns a stable `announce(message)` function. The hook itself mounts no DOM — like the others above, it is a thin adapter that **requires `AriaLiveRegionExtension` from `@lexical/a11y` in the editor's extension tree**. That extension owns the lifecycle of the visually-hidden region (`role=\"status\"`, `aria-atomic`, `aria-live` defaulting to `polite` — configurable via its `politeness` config): the region is created in the extension's `register` step and disposed on the editor's teardown, not on the hook's unmount. `EditorModeAnnounceExtension` (mode transitions via `registerEditableListener`) and `HistoryAnnounceExtension` (undo / redo via `UNDO_COMMAND` / `REDO_COMMAND`) announce through the same region. Both extensions accept optional message overrides for i18n.\n\n## Component ARIA quick reference\n\nWhere Lexical already applies ARIA attributes today (set in each component's `createDOM` / `updateDOM`, declaratively in the surrounding React tree, or applied imperatively via `setAttribute` on a managed or portaled element — as the typeahead menu and the live region do):\n\n| Component | role | aria-\\* attributes |\n| --- | --- | --- |\n| `ToolbarPlugin` (playground) | `toolbar` | `aria-label` |\n| `Modal` (playground) | `dialog` | `aria-modal`, `aria-labelledby` |\n| `LexicalListItemNode` (check list leaf) | `checkbox` | `aria-checked` |\n| `LexicalMenu` typeahead popup | `listbox` | `aria-label` |\n| Editor root (while typeahead is open) | — | `aria-controls`, `aria-activedescendant` |\n| `EquationNode` (playground) | `math` | `aria-label` |\n| `useLexicalAriaLiveRegion` region | `status` | `aria-live`, `aria-atomic` |\n\nCustom nodes follow the same pattern: set the attributes in `createDOM` and re-apply in `updateDOM` when the state they reflect changes. There is no central ARIA contract on `LexicalNode`; treat each subclass's `createDOM` as the source of truth.\n\n## Browser notes\n\nLexical relies on the standard DOM `Escape` contract — verified on Chrome and Safari (macOS, normal window). Safari in fullscreen intercepts `Escape` at the browser level to exit fullscreen; that is the browser's contract, not Lexical's.\n\n## What this page does not cover\n\n- Touch / mobile screen reader gestures. The hooks above share the same DOM contracts with mobile (TalkBack, VoiceOver iOS) but mobile has not been exercised in this set of changes.\n- High contrast / forced-colors theming. See the playground's `index.css` `@media (forced-colors: active)` block for a baseline.\n","packages/lexical-website/docs/concepts/listeners.md":"\n\n# Listeners\n\nListeners are a mechanism that lets the Editor instance inform the user when a certain operation has occurred. All listeners follow a reactive pattern where you can do an operation upon something happening in the future. All listeners also return a function that easily allows for the\nlistener to be unregistered. Below are the different listeners that Lexical supports today:\n\n## `registerUpdateListener`\n\nGet notified when Lexical commits an update to the DOM.\n\n```js\nconst removeUpdateListener = editor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(() => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n });\n});\n\n// Do not forget to unregister the listener when no longer needed!\nremoveUpdateListener();\n```\n\nThe update listener callbacks receives a single argument containing the follow properties:\n\n- `editorState` the latest updated Editor State\n- `prevEditorState` the previous Editor State\n- `tags` a Set of all tags that were passed to the update\n- `dirtyElements` a Map of the NodeKeys of ElementNodes that were marked\n dirty, to a boolean that is true when the node was intentionally mutated\n- `dirtyLeaves` a Set of the NodeKeys of all dirty nodes that are not\n ElementNodes\n- `mutatedNodes` a Map of LexicalNode constructors to a\n `Map`, or null when no DOM was mutated. Only\n populated when at least one MutationListener is registered\n- `normalizedNodes` (advanced) the keys of TextNode descendants that were\n merged with a sibling by normalization\n\nOne thing to be aware of is \"waterfall\" updates. This is where you might schedule an update inside an update\nlistener, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // Read the editorState and maybe get some value.\n editorState.read(() => {\n // ...\n });\n\n // Then schedule another update.\n editor.update(() => {\n // ...\n });\n});\n```\n\nThe problem with this pattern is that it means we end up doing two DOM updates, when we likely could have\ndone it in a single DOM update. This can have an impact on performance, which is important in a text editor.\n\nA listener that re-enqueues work without a stop condition is worse than slow.\nThe editor keeps a cascade budget: once a run of updates re-enqueues more\nthan 100 times without yielding to the event loop, it discards the entire\npending update queue and warns. Bounded activity never reaches the limit —\nthe budget is reset from a macrotask, which a genuine runaway starves — but a\ntrue loop silently loses whatever else was queued.\n\nTo avoid this, we recommend looking into [Node Transforms](transforms.md), which allow you to listen to node changes and\ntransform them as part of the same given update, meaning no waterfalls!\n\n## `registerTextContentListener`\n\nGet notified when Lexical commits an update to the DOM and the text content of the editor changes from\nthe previous state of the editor. If the text content is the same between updates, no notifications to\nthe listeners will happen.\n\n```js\nconst removeTextContentListener = editor.registerTextContentListener(\n (textContent) => {\n // The latest text content of the editor!\n console.log(textContent);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveTextContentListener();\n```\n\n## `registerMutationListener`\n\nGet notified when a specific type of Lexical node has been mutated. There are three states of mutation:\n\n- `created`\n- `destroyed`\n- `updated`\n\nMutation listeners are great for tracking the lifecycle of specific types of node. They can be used to\nhandle external UI state and UI features relating to specific types of node.\n\nIf any existing nodes are in the DOM, and skipInitialization is not true, the listener\nwill be called immediately with an updateTag of 'registerMutationListener' where all\nnodes have the 'created' NodeMutation. This can be controlled with the skipInitialization option,\nwhich defaults to false.\n\n```js\nconst removeMutationListener = editor.registerMutationListener(\n MyCustomNode,\n (mutatedNodes, { updateTags, dirtyLeaves, prevEditorState }) => {\n // mutatedNodes is a Map where each key is the NodeKey, and the value is the state of mutation.\n for (let [nodeKey, mutation] of mutatedNodes) {\n console.log(nodeKey, mutation)\n }\n },\n {skipInitialization: false}\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveMutationListener();\n```\n\n## `registerEditableListener`\n\nGet notified when the editor's mode has changed. The editor's mode can be changed\nvia `editor.setEditable(boolean)`.\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (editable) => {\n // The editor's mode is passed in!\n console.log(editable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\n## `registerDecoratorListener`\n\nGet notified when the editor's decorator object changes. The decorator object contains\nall `DecoratorNode` keys -> their decorated value. This is primarily used with external\nUI frameworks.\n\n```js\nconst removeDecoratorListener = editor.registerDecoratorListener(\n (decorators) => {\n // The editor's decorators object is passed in!\n console.log(decorators);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveDecoratorListener();\n```\n\n## `registerRootListener`\n\nGet notified when the editor's root DOM element (the content editable Lexical attaches to) changes. This is primarily used to\nattach event listeners to the root element. *The root listener function is executed directly upon registration and then on any subsequent update.*\n\n```js\nconst removeRootListener = editor.registerRootListener(\n (rootElement, prevRootElement) => {\n //add listeners to the new root element\n //remove listeners from the old root element\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveRootListener();\n```\n","packages/lexical-website/docs/concepts/named-slots.md":"# Named Slots\n\n:::warning\n\nNamed slots are experimental. The APIs described here are tagged\n`@experimental`, may change without a major version bump, and the\nserialization and collab formats should be treated as unstable until the\nfeature is stabilized.\n\n:::\n\nNamed slots let a single host node (an ElementNode or a DecoratorNode) own\nseveral isolated editable regions addressed by name — a Card's `title`, a\nPullQuote's `quote` and `attribution` — inside the host's own EditorState.\nEach region takes its own caret and formatting, never merges across the\nboundary, and `Cmd+A` doesn't spill into the rest of the document.\n\nBefore named slots, the usual answer was a nested editor per region: every\nregion lives in its own EditorState, so moving nodes between regions and\nkeeping history and collab in sync all require serialization and extra\n`editor.update` passes. The other node shapes don't fit either: plain\nElementNode children share one undivided linked list (Backspace at a region\nstart merges it into the previous region), and a DecoratorNode is atomic, so\nLexical can't own selection, collab, or serialization inside it. With named\nslots, editing a slot is just editing the one tree.\n\n:::note\n\nNamed slots are the model-level generalization of the rendering concept\nbehind [`$getDOMSlot`](/docs/api/modules/lexical#getdomslot) /\n`ElementDOMSlot` in the\n[DOM rendering](../serialization/dom-render.md) documentation. Every\nElementNode already has one _unnamed_ children channel, and `$getDOMSlot`\ncontrols where that channel's content attaches in the node's DOM. Named\nslots are additional, explicitly-named channels alongside it — symmetric in\nthat each renders into a controllable location in the host's DOM — but they\nalso carry the model-level semantics the unnamed channel doesn't: isolation\n(the virtual shadow root below), a separate NodeKey map, and their own\nserialization and collaboration.\n\n:::\n\n## The Model\n\nA host keeps a second child channel, a `Map` of slot name to NodeKey,\nseparate from its ordinary linked-list children. A slot value has its slot\nhost pointer set and `getParent() === null`, with exactly one of the two\nnon-null: `getParent()` stops at the slot boundary, and you climb out only\nthrough [`$getSlotHost()`](/docs/api/modules/lexical#getslothost).\n\nThe slot link itself acts as a **virtual invisible shadow root** between the\nhost and the value. Isolation is structural rather than a convention — an\naccidental boundary crossing surfaces as a thrown invariant, not silent\ncorruption.\n\nIn the DOM, each value renders synchronously into a keyless\n`
\">` container parked slots-first in the host\nDOM as a **hidden placeholder** (`display: none`), in a canonical order\nderived from the host class (see [slot order](#slot-order)). Nothing is\nvisible until the host explicitly attaches the container somewhere (see\n[Rendering](#rendering)) — mirroring how\n[`getDOMSlot`](/docs/api/modules/lexical#getdomslot) gives an element\ncontrol over where its linked-list children render.\n\n## Hosts and Values\n\nAny ElementNode or DecoratorNode can host slots. An ElementNode host can mix\nslots with ordinary children (a Card with a `title` slot plus regular body\nparagraphs); a DecoratorNode host has no children channel, so slots are its\nonly editable content (a PullQuote that is otherwise atomic).\n\nA slot value is any non-inline ElementNode or DecoratorNode. The value's\nshape decides the editing model:\n\n- **A bare block** (for example a ParagraphNode) behaves as a single-line\n field with no extra wrapper in the model, the JSON, or the DOM: its virtual\n scope holds exactly one block, so Enter is a no-op (hosts may map it to\n focus movement) and a multi-block paste flattens to inline content the way\n an `` sanitizes its value — line breaks stripped, block-only\n decorators dropped.\n- **A shadow-root container** (an ElementNode whose\n [`isShadowRoot()`](/docs/api/modules/lexical#isshadowroot) returns\n `true`) behaves as a multi-block region with normal block editing inside.\n\n## Declaring and Setting Slots\n\nA host class declares its slot names in [`$config()`](nodes.mdx); values are\nattached with [`$setSlot`](/docs/api/modules/lexical#setslot):\n\n```ts\nimport {\n $create,\n $createParagraphNode,\n $setSlot,\n ElementNode,\n} from 'lexical';\n\nclass CardNode extends ElementNode {\n $config() {\n return this.config('card', {extends: ElementNode, slots: ['title']});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n}\n\nfunction $createCardNode(): CardNode {\n const card = $create(CardNode);\n // Single-line title: the bare paragraph IS the slot value. An empty\n // paragraph is an empty field; to seed default text, append a non-empty\n // TextNode (empty TextNodes are eliminated during reconciliation).\n $setSlot(card, 'title', $createParagraphNode());\n // Ordinary body child, edited like any other block.\n return card.append($createParagraphNode());\n}\n```\n\nFor a multi-block region, use a shadow-root container as the value:\n\n```ts\nclass SlotContainerNode extends ElementNode {\n $config() {\n return this.config('slot-container', {extends: ElementNode});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n isShadowRoot(): boolean {\n return true;\n }\n}\n\n$setSlot(\n pullQuote,\n 'quote',\n $create(SlotContainerNode).append(\n $createParagraphNode().append($createTextNode('First block')),\n $createParagraphNode().append($createTextNode('Second block')),\n ),\n);\n```\n\nThe core API surface (all exported from `lexical`):\n\n- [`$setSlot(host, name, node)`](/docs/api/modules/lexical#setslot) — place a value into a named slot, replacing\n any existing value under that name. Move semantics, mirroring `append`:\n the value is detached from any current parent or slot first. Throws if the\n value is inline or if the name is one of the reserved prototype keys\n (`__proto__`, `constructor`, `prototype`). Slotting a node into its own\n descendant would form a cycle; this is checked (and throws) in development\n only — in production it behaves like appending an ancestor through the\n children channel, which is likewise unguarded.\n- [`$getSlot(host, name)`](/docs/api/modules/lexical#getslot) — the value under a name, or `null`.\n- [`$getSlotNames(host)`](/docs/api/modules/lexical#getslotnames) — the host's slot names in canonical order.\n- [`$removeSlot(host, name)`](/docs/api/modules/lexical#removeslot) — detach the value under a name (the subtree is\n garbage-collected unless you reattach it elsewhere).\n- [`$getSlotHost(node)`](/docs/api/modules/lexical#getslothost) — the host a value is slotted into, or `null`.\n- [`$getSlotNameWithinHost(node)`](/docs/api/modules/lexical#getslotnamewithinhost) — the name of the slot\n a value occupies on its host (the reverse direction of `$getSlotHost`), or\n `null` when the node is not a slot value.\n- [`$getSlotFrame(node)`](/docs/api/modules/lexical#getslotframe) — the innermost slot value containing a node (the\n \"frame\" whose virtual shadow root scopes editing), or `null` when the node\n is not inside any slot.\n- [`$getSelectionSlotFrame(selection)`](/docs/api/modules/lexical#getselectionslotframe) — the slot frame a\n selection lives in, or `null` when it is outside any slot. Selection-driven\n exporters walk this frame instead of the root's children, because a\n selection inside a slot never contains its host and a root walk would\n export nothing. Works for every selection type, not just `RangeSelection`.\n- [`$isSlotHost(node)`](/docs/api/modules/lexical#isslothost) /\n [`$isSlotChild(node)`](/docs/api/modules/lexical#isslotchild) — type guards\n for the [`SlotHostNode`](/docs/api/modules/lexical#slothostnode) /\n [`SlotChildNode`](/docs/api/modules/lexical#slotchildnode) interfaces.\n\n## Slot Order\n\nSlot order is canonical and derived, never stored. Names declared in\n`$config()` (`slots: ['quote', 'attribution']`) sort first in declaration\norder; undeclared names sort after them, lexicographically by UTF-16 code\nunit (plain JavaScript string comparison, locale-independent). `$setSlot`\nre-canonicalizes on every write, so documents normalize on load and\nconcurrent collaborative additions converge to the same order on every\nclient. If presentation order matters, declare the names.\n\n## Rendering\n\nThe reconciler always renders every slot subtree synchronously, but into a\nhidden placeholder container — visibility is the host's explicit decision.\nThere are three ways to attach a slot, all sharing the same contract\n(attaching moves the container to the target, a no-op when it is already\nthere, and reveals it; the container renders as a normal block):\n\n1. **Synchronously in-lexical**: register a `$getSlotTargetElement`\n [`DOMRenderMatch`](/docs/api/modules/lexical_html#domrendermatch)\n override for the host's node class (a\n [DOM render override](../serialization/dom-render.md), not a node\n method — this is an advanced hook). The reconciler consults it whenever\n it creates or reconciles the slot's container and attaches/reveals\n within the same commit — no listener or framework hop. Returning\n `hostDom` reveals the slot in its default slots-first position:\n\n ```ts\n import {domOverride, DOMRenderExtension} from '@lexical/html';\n import {configExtension, defineExtension} from 'lexical';\n\n export const CardExtension = defineExtension({\n dependencies: [\n configExtension(DOMRenderExtension, {\n overrides: [\n domOverride([CardNode], {\n // Reveal the title in its default slots-first position within\n // the same commit that renders it. Returning an element from\n // deeper inside the host's DOM attaches it there instead;\n // $next() defers to lower-priority overrides (default: null,\n // a hidden placeholder).\n $getSlotTargetElement: (node, slotName, hostDom, $next, editor) =>\n hostDom,\n }),\n ],\n }),\n ],\n name: 'card',\n nodes: [CardNode],\n });\n ```\n\n2. **Imperatively**:\n [`mountSlotContainer(editor, nodeKey, slotName, target)`](/docs/api/modules/lexical#mountslotcontainer)\n and\n [`unmountSlotContainer(editor, nodeKey, container)`](/docs/api/modules/lexical#unmountslotcontainer)\n from `lexical` are the framework-independent primitives (e.g. from a\n [mutation listener](/docs/api/modules/lexical#registermutationlistener),\n which fires after the commit). `mountSlotContainer` resolves the container\n against the committed editor state\n ([`editor.getEditorState()`](/docs/api/modules/lexical#geteditorstate)), so\n the model it reads matches the reconciled DOM it reveals;\n `unmountSlotContainer` takes the container you already hold and only touches\n the DOM:\n\n ```ts\n import {mountSlotContainer} from 'lexical';\n\n // e.g. inside an extension's register(editor):\n const unregister = editor.registerMutationListener(\n CardNode,\n (mutations) => {\n for (const [nodeKey, mutation] of mutations) {\n if (mutation === 'destroyed') {\n continue;\n }\n const hostDom = editor.getElementByKey(nodeKey);\n if (hostDom !== null) {\n // Mounting in place: the placeholder is already parked in the\n // host DOM, so this just reveals it in its slots-first position.\n // Any element within the host's DOM works as a target.\n mountSlotContainer(editor, nodeKey, 'title', hostDom);\n }\n }\n },\n {skipInitialization: false},\n );\n ```\n\n `unmountSlotContainer(editor, nodeKey, container)` is the reverse: it\n hides the container and parks it back in the host DOM, for when a mount\n target goes away while the host remains.\n\n3. **From React chrome**: the\n [`useLexicalSlotRef`](/docs/api/modules/lexical_react_useLexicalSlotRef#uselexicalslotref)\n hook from `@lexical/react/useLexicalSlotRef` wraps the imperative pair and returns a\n ref that mounts a slot's container into your component — the usual choice\n for a DecoratorNode host's `decorate()` chrome (whose containers are\n opted back into `contentEditable` automatically, since the decorator DOM\n is non-editable):\n\n```tsx\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {useLexicalSlotRef} from '@lexical/react/useLexicalSlotRef';\n\nfunction PullQuoteComponent({nodeKey}: {nodeKey: NodeKey}) {\n const [editor] = useLexicalComposerContext();\n const quoteRef = useLexicalSlotRef(editor, nodeKey, 'quote');\n const attributionRef = useLexicalSlotRef(\n editor,\n nodeKey,\n 'attribution',\n );\n return (\n
\n
\n
\n
\n );\n}\n```\n\nA `contentEditable=false` ElementNode shell can host React chrome the same\nway (slot containers opt into editing whenever the host DOM is\nnon-editable): the playground's Review demo portals chrome into the host DOM,\nattaches the author slot with `useLexicalSlotRef`, drives an interactive\nstar-rating widget that persists to NodeState, and applies the identical\nhidden-then-attach technique to its `getDOMSlot` children element. Such a shell should call\n[`setDOMUnmanaged(dom)`](/docs/api/modules/lexical#setdomunmanaged) in\n`createDOM` — the portal and the\nattach moves mutate the shell's children from outside the reconciler, and\nthe marker gives the shell the same mutation-observer exemption a\nDecoratorNode's DOM has.\n\n## Editable state\n\nA slot rendered inside a non-editable host (a DecoratorNode, or a\n`contentEditable=false` element shell) would not track the editor's editable\nstate on its own, so the reconciler gives its container an explicit\n`contentEditable` that follows `editor.isEditable()`, and re-renders the islands\nwhenever `setEditable` toggles — so a read-only editor's slots are not left\neditable. No extension is required. Slots always follow the editor; there is\ncurrently no way for a slot to override its own editable state.\n\nA host that attaches its own editable island which is *not* a slot container —\nfor example the Review demo's `getDOMSlot` children element inside its\n`contentEditable=false` shell — opts it into the same behavior with\n[`$markSlotEditable(element, editor)`](/docs/api/modules/lexical#marksloteditable),\nre-applying it from `updateDOM` so an editable toggle reaches the island.\n\n## Editing Behavior\n\n- **Selection never crosses a slot boundary.** Selections are clamped to the\n anchor's slot frame at every entry point (DOM resolution,\n [`$setSelection`](/docs/api/modules/lexical#setselection),\n and point mutation), so a mouse drag and a `shift+arrow` across the\n boundary land on the same clamped result. A focus in a slot of a host is\n moved past the whole host, or to the edge of the host's own children when\n the selection starts inside the host.\n- **Deletion stops at the boundary.** Backspace at the start of a slot and\n forward-Delete at its end are no-ops instead of merging across the virtual\n shadow root.\n- **`Cmd+A` scopes to the slot frame** when the caret is inside one; outside\n slots the default handlers keep the legacy whole-document behavior.\n Progressive expansion (block → enclosing slot frame → document on repeated\n presses) is provided by the opt-in\n [`SelectBlockExtension`](/docs/api/modules/lexical_extension#selectblockextension)\n from `@lexical/extension`.\n- **Generic block conversion skips slot values.** A slot value has no\n parent — its up-link is `$getSlotHost` — so selection-driven block\n converters (`$setBlocksType`, `$wrapNodes`, `$insertList` / `$removeList`,\n the markdown block shortcuts) treat it as ineligible and do nothing rather\n than replace it: the slot assignment is managed by the node or extension\n that owns the slot. Calling `LexicalNode.replace` directly on a slot value\n throws; reassign the slot with `$setSlot` on its host instead.\n- **Slots stay bound to their host through `replace`.** Replacing a slot\n *host* (`host.replace(other)`) does not transfer its slots to the\n replacement — slots are not necessarily portable across node types, so the\n slot map travels with the node, never with its position. If the replaced\n host is reattached in the same update (the\n [`$wrapNodeInElement`](/docs/api/modules/lexical_utils#wrapnodeinelement)\n pattern) it keeps its slots; if it stays detached, its slot subtrees are\n garbage-collected with it. The same applies to anything built on `replace`:\n converting a slot host with `$setBlocksType` produces a slot-less\n replacement block. Move a slot onto another host explicitly with\n `$setSlot`.\n- **A NodeSelection of an element carries its children.** Copy and export\n of a whole-host NodeSelection (e.g. a chrome click that selects \"the whole\n Card\") include the host's body children even though they aren't in the\n selection themselves — the old shell-only output made cut silently lossy.\n This applies only to NodeSelection; a partial RangeSelection over the host\n keeps per-child slicing.\n\n### Traversal is intentionally asymmetric\n\nContent reads include slot subtrees, slots-first:\n[`getTextContent()`](/docs/api/modules/lexical#gettextcontent),\n[`getAllTextNodes()`](/docs/api/modules/lexical#getalltextnodes),\nand the [`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots)\nfamily in `@lexical/utils` count slot content for search, copy, and\naccessibility. Navigation excludes them:\n[`getChildren()`](/docs/api/modules/lexical#getchildren),\n[`getFirstDescendant()`](/docs/api/modules/lexical#getfirstdescendant)\nand friends stay linked-list-only, so caret movement never walks into a slot\nby accident. Choose [`$dfs`](/docs/api/modules/lexical_utils#dfs) or\n[`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots) depending on whether \"this subtree\" should mean the\nnavigable tree or all content.\n\n## Serialization\n\nJSON serialization is automatic in both directions. A host's slots serialize\nunder the reserved `$slots` key on\n[`SerializedLexicalNode`](/docs/api/modules/lexical#serializedlexicalnode)\n(a sibling of\nNodeState's reserved `'$'` key), keyed by slot name:\n\n```json\n{\n \"type\": \"card\",\n \"version\": 1,\n \"$slots\": {\n \"title\": {\"type\": \"paragraph\", \"children\": [], \"version\": 1}\n },\n \"children\": []\n}\n```\n\nParsing re-attaches each subtree with `$setSlot` and throws if `$slots`\nappears on a node that cannot host slots. The `$` prefix keeps the\nframework-owned key from colliding with a subclass that already serializes a\n`slots` property of its own.\n\nHTML serialization is opt-in per host, like NodeState: the exporter never\ndescends into slots on its own. A host's `exportDOM` can emit each slot into\na wrapper using\n[`$appendNodeToHTML`](/docs/api/modules/lexical_html#appendnodetohtml) from\n`@lexical/html`, and a\n[DOM import rule](../serialization/dom-import.md) on the host's\ndistinguishing markup maps the wrappers back through `$setSlot`.\n\n## Collaboration\n\nSlots sync on both the V1 and V2 Yjs bindings through a per-slot-diffed\n`Y.Map` stored under the reserved `__slots` attribute key on the host's shared\ntype (the channel reuses the host's `__slots` field name, which is already\nexcluded from the property sync). Hosts with declared slots create that map\neagerly, so two clients\nconcurrently setting *different* slot names for the first time merge\nper-entry instead of racing. Malformed or hostile remote entries are\nvalidated and skipped.\n\n:::caution\n\nPre-slots clients receiving slot data from upgraded peers will error rather\nthan render it. Enabling slots in long-lived shared documents should be\ngated on all participants running a slots-aware version; new clients\ntolerate unknown slot data going forward.\n\n:::\n\n## Reserved Names\n\nAdding slots reserves a few identifiers that custom node subclasses should\nnot define for their own purposes:\n\n- the `__slots` and `__slotHost` fields on ElementNode / DecoratorNode — the\n `__slots` name is also the collab attribute key for the slots channel, so it\n is reserved on the Yjs shared type too;\n- the `$slots` serialized JSON key.\n\n## Current Limitations\n\n- The caret / NodeCaret APIs throw across a slot boundary (\"no common\n ancestor\"); slot-aware caret traversal is a planned follow-up.\n- Nested slots (a slot whose host is itself slotted) are only handled one\n level deep by the runtime selection comparator.\n- The mixed-version collab caveat above.\n","packages/lexical-website/docs/concepts/node-cloning.md":"# Node Cloning\n\nUnderstanding how to properly clone and modify nodes is crucial for working with Lexical. This guide explains the different cloning mechanisms and when to use each one.\n\n## Types of Node Cloning\n\nLexical provides several ways to clone nodes, each serving a different purpose:\n\n1. `static clone()` - Internal API for state management\n2. `$copyNode()` - Public API for creating new nodes\n3. `getWritable()` - Public API for node modifications\n\n## The `clone` Method\n\n### What is `clone`?\n\nThe `clone` method is a static method that creates the next version of a node. A node that declares [`$config()`](./nodes.mdx) has one synthesized for it and need not implement it — a hand-written `clone` is only required for a node that does not use `$config()`, or whose constructor has required arguments. Either way, it's important to understand that this is an **internal API** used by Lexical's state management system.\n\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n // ✅ Correct implementation\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### When is `clone` Used?\n\n1. **Internal State Management**\n - Used by Lexical internally\n - Part of the editor's state update system\n - Called by `getWritable()`\n\n2. **Node Mutations**\n ```typescript\n // Example of a node method implementation\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n }\n\n node.setData(\"new data\");\n ```\n\n### When NOT to Use `clone`?\n\n```typescript\n// ❌ Never do this\nfunction $duplicateNode(node: MyCustomNode) {\n return MyCustomNode.clone(node); // Don't call clone directly\n}\n```\n\n## The `afterCloneFrom` Method\n\n### What is `afterCloneFrom`?\n\n`afterCloneFrom(prevNode)` runs on every clone, right after it is constructed,\nand copies over whatever the constructor did not. The base implementation\ncarries the node's links to its parent and siblings and its\n[NodeState](./node-state.md), and `ElementNode` and `TextNode` carry their own\nbuilt-in properties such as format, style, and indent. A property that is\ncopied neither by the constructor nor by some `afterCloneFrom` silently\nreverts to its default on the node's next write.\n\n### When you don't need it\n\nWith the modern APIs you usually don't write one at all:\n\n- **Serialization schema.** A property declared as a field in a `$config`\n [`json` schema](./nodes.mdx#creating-custom-nodes-with-a-serialization-schema)\n (`withField(stringValue(), {field: '__label'})`) is carried across the\n clone for you, because the schema says where it is stored. Available in\n Lexical v0.51.0 and later.\n- **NodeState.** State created with `createState` and stored with `$setState`\n is carried by the base `afterCloneFrom`, so a node whose extra data lives\n only in NodeState needs nothing.\n\n```ts\n// At module scope, above the class, so TypeScript checks it against the class\nconst calloutSchema = nodeSchema()({\n label: withField(stringValue(), {field: '__label'}),\n});\n\nclass CalloutNode extends ElementNode {\n __label: string = '';\n\n // No afterCloneFrom: `__label` is declared as a field in calloutSchema, so\n // it is carried across every clone.\n $config() {\n return this.config('callout', {extends: ElementNode, json: calloutSchema});\n }\n}\n```\n\n### When you still need it\n\nOverride `afterCloneFrom` for a property that neither of those covers: a\nfield that isn't in the node's schema, one declared only through accessor\nmethods (see\n[Carrying properties across a clone](../serialization/serialization.md#carrying-properties-across-a-clone)),\nor any property of a node written without a schema. Always call\n`super.afterCloneFrom(prevNode)` first so the inherited properties and\nNodeState are still carried:\n\n```ts\nclass MyCustomNode extends ElementNode {\n __data: string = '';\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__data = prevNode.__data;\n }\n}\n```\n\nLike `clone`, `afterCloneFrom` is called by Lexical; don't call it yourself\nexcept through `super`.\n\n## Using `$copyNode`\n\n### What is `$copyNode`?\n\n`$copyNode` is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node.\nBy default, all properties and `NodeState` will be copied to the new node, and then `resetOnCopyNodeFrom` will be called to\nallow the node to optionally reset certain properties (and NodeState configured with `resetOnCopyNode: true`) to defaults\n(such as the checked state of a `ListItemNode`).\n\n```typescript\n// ✅ Correct: Using $copyNode\nconst copy = $copyNode(existingNode);\n```\n\n### When to Use `$copyNode`?\n\n1. **Creating Duplicates**\n ```typescript\n // ✅ Correct: Duplicating a node\n const duplicate = $copyNode(originalNode);\n someParent.append(duplicate);\n ```\n\n## Using `getWritable`\n\n### What is `getWritable`?\n\n`getWritable` is an internal API used within node method implementations to get a mutable version of a node. Node consumers should use the node's public methods instead.\n\n```typescript\n// ✅ Correct: Implementation of a node method\nclass MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n}\n\n// ✅ Correct: Using the node\nconst node = new MyCustomNode();\nnode.setData(\"new value\");\n```\n\n## Common Patterns\n\n### Modifying Nodes\n\n```typescript\n// ✅ Correct: Modifying a node\nfunction $updateNodeData(node: MyCustomNode, newData: string): MyCustomNode {\n return node.setData(newData);\n}\n\n// ❌ Incorrect: Don't clone manually\nfunction $updateNodeDataWrong(node: MyCustomNode, newData: string): MyCustomNode {\n const clone = MyCustomNode.clone(node);\n clone.setData(newData);\n return clone;\n}\n```\n\n### Copying Nodes\n\n```typescript\n// ✅ Correct: Copying a node\nfunction $duplicateNode(node: MyCustomNode): MyCustomNode {\n return $copyNode(node);\n}\n\n// ❌ Incorrect: Don't use clone\nfunction $duplicateNodeWrong(node: MyCustomNode): MyCustomNode {\n return node.constructor.clone(node);\n}\n```\n\n## Performance Considerations\n\n1. **Referential Integrity**\n - `getWritable()` ensures proper EditorState updates with new clones\n - Prevents \"orphaned\" nodes that won't be rendered\n\n2. **State Management**\n ```typescript\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data; // Properly tracked by editor\n return self;\n }\n }\n ```\n\n## Testing\n\n```typescript\ntest('node modification', async () => {\n await editor.update(() => {\n const node = new MyCustomNode(\"test\");\n \n node.setData(\"new data\");\n \n // ✅ Correct: Use $copyNode for duplication\n const copy = $copyNode(node);\n });\n});\n```\n\n## Related Concepts\n\n- [Editor State](editor-state.md) - How cloning affects editor state\n- [Nodes](nodes.mdx) - Core concepts about Lexical nodes\n\n## Common Questions\n\n**Q: How do I duplicate a node?**\nA: Use `$copyNode(node)` to create a new copy with a new key.\n\n**Q: When should I use clone?**\nA: Never directly. Use `$copyNode()` or `getWritable()` instead. ","packages/lexical-website/docs/concepts/node-replacement.md":"# Node Replacement\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a subclass.\n\n## Use Case\n\n:::note\n\nIn earlier versions of this documentation, \"Node Replacement\" was called \"Node Overrides\".\nWe've changed the name to match the terms used in the implementation.\n\n:::\n\n:::tip\n\nIf your use case only requires adding ad-hoc data to existing nodes, you may be able to use the [NodeState](node-state.md) API instead of subclassing and node replacement.\n\n:::\n\nSome of the most commonly used Lexical Nodes are owned and maintained by the core library. For example, ParagraphNode, HeadingNode, QuoteNode, List(Item)Node etc - these are all provided by Lexical packages, which provides an easier out-of-the-box experience for some editor features, but makes it difficult to override their behavior. For instance, if you wanted to change the behavior of ListNode, you would typically extend the class and override the methods. However, how would you tell Lexical to use *your* ListNode subclass in `ListExtension` instead of using the core ListNode? That's where Node Replacement can help.\n\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a different node class. This can be done through the `nodes` of an extension:\n\n```ts\nconst CustomParagraphExtension = defineExtension({\n name: '@my-app/CustomParagraph',\n nodes: () => [\n // Don't forget to register your custom node separately!\n CustomParagraphNode,\n {\n replace: ParagraphNode,\n with: (node: ParagraphNode) => {\n return $createCustomParagraphNode();\n },\n withKlass: CustomParagraphNode,\n },\n ],\n});\n```\nIn the snippet above,\n- `replace`: Specifies the core node type to be replaced. \n- `with`: Defines a transformation function to replace instances of the original node to the custom node. \n- `withKlass`: This option ensures that behaviors associated with the original node type work seamlessly with the replacement. For instance, node transforms or mutation listeners targeting ParagraphNode will also apply to CustomParagraphNode when withKlass is specified. Without this option, the custom node might not fully integrate with the editor's built-in features, leading to unexpected behavior.\n\nOnce this is done, Lexical will replace all ParagraphNode instances with CustomParagraphNode instances. One important use case for this feature is overriding the serialization behavior of core nodes. Check out the full example below.\n\n## Node Replacement Example\n\nThis example demonstrates using Node Replacement to replace all `ParagraphNode` with a `CustomParagraphNode` that overrides `createDOM`.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-replacement?file=src/main.tsx)\n\n\n","packages/lexical-website/docs/concepts/node-state.md":"# NodeState\n\nThe NodeState API introduced in v0.26.0 allows arbitrary state to be added\nad-hoc to any node in a way that participates with reconciliation, history,\nand JSON serialization.\n\n## Use Case\n\nNodeState allows your application to define keys that can be stored on\nany node with automatic JSON support.\n\n:::tip\n\nYou can even add node state to the RootNode to store document-level metadata.\n\n:::\n\nWith a combination of NodeState and other APIs such as\n[Listeners](listeners.md) or\n[Transforms](transforms.md) you can\nlikely shape the editor to meet your needs without having to do much\n[Node Customization](node-replacement.md).\n\nEven when you are subclassing nodes, using NodeState instead of additional\nproperties to store the node's data can be [more efficient](#efficiency)\nand will save you from writing a lot of boilerplate in the constructor,\nupdateFromJSON, and exportJSON.\n\n## Usage\n\n### createState\n\n[createState](/docs/api/modules/lexical#createstate)\ncreates a\n[StateConfig](/docs/api/modules/lexical#stateconfig)\nwhich defines the key and configuration for your NodeState value.\n\nThe key must be locally unique, two distinct StateConfig must not have the\nsame string key if they are to be used on the same node.\n\nTypical usage will look something like this:\n\n```ts\nconst questionState = createState('question', {\n parse: (v) => (typeof v === 'string' ? v : ''),\n});\n```\n\nThe required `parse` function serves two purposes:\n- It provides a type-safe and runtime-safe way to parse values that were\n serialized to JSON\n- When called with `undefined` (or any invalid value) it should return some\n default value (which may be `undefined` or `null` or any other value you\n choose)\n\nIn this case, the question must be a string, and the default is an\nempty string.\n\nSee the\n[createState](/docs/api/modules/lexical#createstate)\nAPI documentation for more details, there are other optional settings\nthat you may want to define particularly if the value is not a primitive\nvalue such as boolean, string, number, null, or undefined.\n\n:::tip\n\nInstead of writing parse functions by hand, use the\n[serialization schema combinators](/docs/serialization/#declarative-serialization-schemas-with-config)\nfrom `lexical`, such as `stringValue`, `numberValue`, `enumValue`,\n`arrayValue`, `objectValue`, and `nullable`. They are the same ones a node's\n`$config` JSON schema uses. A schema is itself a parse function, so it can be\npassed directly as `parse`:\n\n```ts\nimport {arrayValue, createState, stringValue} from 'lexical';\n\nconst questionState = createState('question', {parse: stringValue()});\nconst tagsState = createState('tags', {parse: arrayValue(stringValue())});\n```\n\nBecause `parse` is just a function, the combinators also compose with schema\nlibraries such as [zod](https://zod.dev/), [ArkType](https://arktype.io/),\n[Effect](https://effect.website/), and [Valibot](https://valibot.dev/). Wrap a\nlibrary's validator in a parse function that returns a default for invalid\ninput, or use `transformValue` to refine what a combinator parsed.\n\n:::\n\n### $getState\n\n[$getState](/docs/api/modules/lexical#getstate) gets the\nNodeState value from the given node, or the default if that key was never\nset on the node.\n\n```ts\nconst question = $getState(pollNode, questionState);\n```\n\nSee also\n[$getStateChange](/docs/api/modules/lexical#getstatechange)\nif you need an efficient way to determine if the state has changed on two\nversions of the same node (typically used in updateDOM, but may be useful in\nan update listener or mutation listener).\n\n### $setState\n\n[$setState](/docs/api/modules/lexical#setstate) sets the\nNodeState value on the given node.\n\n```ts\nconst question = $setState(\n pollNode,\n questionState,\n 'Are you planning to use NodeState?',\n);\n```\n\n:::tip\n\nThe last argument is a ValueOrUpdater, just like with React's useState\nsetters. If you use an updater function and the value does not change,\nthe node and its NodeState *won't* be marked dirty.\n\n:::\n\n## Serialization\n\nThe NodeState for a node, if any values are set to non-default values, is\nserialized to a record under a single\n[NODE_STATE_KEY](/docs/api/modules/lexical#node_state_key)\nwhich is equal to `'$'`.\n\n```json\n{\n \"type\": \"poll\",\n \"$\": {\n \"question\": \"Are you planning to use NodeState?\"\n }\n}\n```\n\n:::tip\n\nBy default, it is assumed that your parsed values are JSON serializable,\nbut for advanced use cases you may use values such as Date, Map, or Set\nthat need to be transformed before JSON serialization. See the\n[StateValueConfig](/docs/api/modules/lexical#statevalueconfig)\nAPI documentation.\n\n:::\n\n### Flat serialization with `$config`\n\nNodes that declare a `StateConfig` in [`$config`](nodes.mdx#creating-custom-nodes-with-config-and-nodestate)\nwith `flat: true` lift that key to the top level of the serialized node\ninstead of nesting it under `'$'`. This makes the JSON shape identical\nto a legacy node that stored the value as a `__property` instance\nvariable, so existing payloads continue to round-trip after the node is\nmigrated to NodeState.\n\nFor example, a `ColoredNode` that extends `TextNode` and declares a flat\n`color` state (see [Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\n$config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n}\n```\n\nserializes as:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"color\": \"red\"\n}\n```\n\nA non-flat (default) state on the same node would instead appear under\n`'$'`:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"$\": {\n \"color\": \"red\"\n }\n}\n```\n\nIn both cases, a key is only emitted when the current value is not equal\nto the default returned by its `parse` function — see\n[Efficiency](#efficiency).\n\n:::note\n\nDon't reuse a flat key that a superclass already serializes (e.g. `text`\non `TextNode`).\n\n:::\n\n### Upgrading a legacy JSON property to NodeState\n\nA node that stores data as a `__property` instance variable with custom\n`exportJSON`/`importJSON`/`updateFromJSON` can be migrated to NodeState\nwith `flat: true` without changing its serialized JSON shape.\n\nBefore — `ColoredNode` with a `__color` property and hand-written\nserialization (see the full legacy example in\n[Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\nexport type SerializedColoredNode = Spread<\n {color?: string},\n SerializedTextNode\n>;\n\nexport class ColoredNode extends TextNode {\n __color: string;\n\n constructor(text: string = '', color: string = DEFAULT_COLOR, key?: NodeKey) {\n super(text, key);\n this.__color = color;\n }\n\n static getType(): string {\n return 'colored';\n }\n\n static clone(node: ColoredNode): ColoredNode {\n return new ColoredNode(node.__text, node.__color, node.__key);\n }\n\n static importJSON(serializedNode: SerializedColoredNode) {\n return new ColoredNode().updateFromJSON(serializedNode);\n }\n\n updateFromJSON(serializedNode: SerializedColoredNode) {\n const self = super.updateFromJSON(serializedNode);\n self.__color =\n typeof serializedNode.color === 'string'\n ? serializedNode.color\n : DEFAULT_COLOR;\n return self;\n }\n\n exportJSON(): SerializedColoredNode {\n return {\n ...super.exportJSON(),\n color: this.__color === DEFAULT_COLOR ? undefined : this.__color,\n };\n }\n}\n```\n\nAfter — same on-the-wire JSON, no hand-written serialization:\n\n```ts\nconst colorState = createState('color', {\n parse: (v) => (typeof v === 'string' ? v : DEFAULT_COLOR),\n});\n\nexport class ColoredNode extends TextNode {\n $config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n }\n}\n```\n\nNo `exportJSON`, `importJSON`, `updateFromJSON`, `clone`, or\n`afterCloneFrom` override is needed: `$config` installs `clone` and\n`importJSON`, and the base `exportJSON`/`updateFromJSON`/`afterCloneFrom`\non `LexicalNode`/`TextNode` already round-trip NodeState. Read the color\nvia `$getState(node, colorState)` and write it via\n`$setState(node, colorState, value)` instead of `node.__color`.\n\n:::tip\n\nFor a seamless migration, keep the JSON key name the same — for a flat\nstate, that's the first argument to `createState`. Migrating from a\nnon-flat NodeState to a flat NodeState also works: state that appears\nunder the `$` (`NODE_STATE_KEY`) is still parsed even when the state is\nconfigured as flat, and the flat value takes precedence when both are\npresent.\n\n:::\n\n## Efficiency\n\nNodeState uses a copy-on-write scheme to manage each node's state. If\nnone of the state has changed, then the NodeState instance will be\nshared across multiple versions of that node.\n\n:::info\n\nIn a given reconciliation cycle, the first time a Lexical node is marked dirty\nvia `getWritable` will create a new instance of that node. All properties\nof the previous version are set on the new instance. NodeState is stored\nas a single property, and no copying of the internal state is done\nuntil the NodeState itself is marked writable.\n\n:::\n\nWhen serializing to JSON, each key will only be stored if the value\nis not equal to the default value. This can save quite a lot of space\nand bandwidth.\n\nParsing and serialization is only done at network boundaries, when\nintegrating with JSON or Yjs. When a value changes from an external\nsource, it is only parsed once the first time it is read.\nValues that do not come from external sources are not parsed, and\nvalues that are not used are never parsed.\n\n## Capabilities\n\nCurrent:\n\n- Allows you to define and add state to any node\n- Serializes that state automatically in the node's JSON, supporting\n versioning and copy+paste\n- Works with the reconciler, TextNodes with differing state will not\n be implicitly merged\n- @lexical/yjs support, NodeState will be automatically synchronized\n like any other property\n- NodeState values that are not used will simply pass-through, making\n it a bit easier for situations where multiple configurations are used\n on the same data (e.g. older and newer versions of your editor,\n a different set of plugins based on context, etc.).\n- Pre-registration system for nodes to declare expected state\n and serialize them as top-level properties (`flat`) with `$config`\n (see [#7260](https://github.com/facebook/lexical/issues/7260)).\n- Can be integrated with\n [DOMRenderExtension](../serialization/dom-render.md) for editor\n rendering and HTML export\n- Can be integrated with\n [DOMImportExtension](../serialization/dom-import.md) for HTML import\n\nFuture:\n\n- Does not yet support direct integration with Yjs, e.g.\n you can not store a Y.Map as a NodeState value\n (see [#7293](https://github.com/facebook/lexical/issues/7293))\n\n## Node State Style Example\n\nThis example demonstrates an advanced use case of storing a style object on TextNode using NodeState.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-state-style?file=src/main.tsx)\n\n\n","packages/lexical-website/docs/concepts/one-lexical-per-app.md":"---\nsidebar_label: One Lexical per app\n---\n\n# One Lexical per app\n\n`lexical` is effectively a singleton **within one app**: an app must resolve\nexactly **one** copy of `lexical`, and one copy of each `@lexical/*` package it\nuses. Two copies in the same bundle do not merely waste bytes — they break the\neditor in ways whose error messages point nowhere near the real cause.\n\nThe practical consequence, covered in [Publishing a library](#publishing-a-library)\nbelow: **a library built on Lexical declares `lexical` and the `@lexical/*`\npackages it imports as `peerDependencies`, never as `dependencies`. The\napplication brings its own Lexical.**\n\n:::note\n\nThis page is about npm `peerDependencies` in your `package.json`. Extensions\nhave their own, unrelated notion of\n[peer dependencies](../extensions/peer-dependencies.md) — optional links between\nextensions inside one editor.\n\n:::\n\n## The boundary is the app, not the page\n\nSeveral self-contained apps can share a page, each with its own bundled copy of\nLexical, and that is fine — a CMS page with two independently deployed widgets\non it, or a micro-frontend setup, does not have a bug just because two copies of\n`lexical` are loaded. Lexical anticipates this: `isLexicalEditor()` is an\n`instanceof` check specifically \"to prevent issues with multiple embedded\nLexical installations\", and an editor is tagged on its own root element rather\nthan in any page-global registry, so each app's editors resolve to that app's\nLexical and ignore the others.\n\nWhat those apps cannot do is interoperate. Two copies have no compatible API\nsurface between them, so treat each as a sealed island:\n\n- do not pass nodes, editors, `EditorState` objects, selections or commands\n across the boundary — pass serialized JSON or HTML, which is data rather than\n identity;\n- a plugin, node package or shared editor config must be bundled with the app it\n serves, not shared as a live import between apps;\n- `@lexical/react` context does not cross the boundary either, since the context\n object itself comes from one copy.\n\nThe rest of this page is about the failure case: two copies **inside one app**,\nwhere code from copy A is expected to work with an editor from copy B.\n\n## Why one copy per app\n\nLexical keeps state at module scope, and identifies things by reference rather\nthan by name. Both assumptions hold only within a single copy of the module.\n\n- **The active editor is module state.** `activeEditor`, `activeEditorState`\n and `isReadOnlyMode` live at module scope in `LexicalUpdates.ts`, and every\n `$` function reads them. `editor.update()` in copy A sets copy A's variables;\n a `$` function imported from copy B reads copy B's, which are still `null`\n ([Editor State](editor-state.md)).\n- **Node classes are compared by identity.** Node registration and the\n `instanceof LexicalNode` checks compare class references. A node that extends\n `LexicalNode` from copy A is not, as far as copy B is concerned, a\n `LexicalNode` at all — even though both classes have the same name and come\n from the same published version ([Nodes](nodes.mdx)).\n- **Commands are object identities.** `createCommand()` returns a fresh `{type}`\n object, and `registerCommand`/`dispatchCommand` match on that object, not on\n its `type` string. Two copies of `lexical` export two distinct\n `FORMAT_TEXT_COMMAND` objects, so a dispatch from one never reaches a listener\n registered with the other ([Commands](commands.md)).\n\nOn top of that, two copies are usually two *versions*, which is API drift inside\na single editor: half your plugins were compiled against a different API and\nserialization format than the editor running them, and the mismatch surfaces\nonly at runtime, on the paths that happen to differ.\n\n## Symptoms of a duplicated Lexical\n\nThe errors are unhelpfully literal — a class that plainly does implement\n`getType()` is reported as not implementing it, because the check is running\nagainst the other copy:\n\n```\nLexicalNode: Node FooNode does not implement .getType().\n\nCreate node: Type heading in node HeadingNode does not match registered node\nHeadingNode with the same type\n\ncreateEditor: nodes[0] FooNode (type foo) is not a constructor that subclasses\nLexicalNode from the lexical package used by this editor (0.50.0)\n\nUnable to find an active editor state. State helpers or node methods can only be\nused synchronously during the callback of editor.update(), editor.read(), or\neditorState.read(). Detected on the page: 0 compatible editor(s) with version\n0.50.0 and incompatible editors with versions 0.49.0\n```\n\nThat last sentence is Lexical telling you directly that it found editors built\nfrom another copy — a version different from its own, or the same version marked\n`(separately built, likely a bundler configuration issue)`. Note that this\ndiagnostic scans the whole page, so a genuinely separate app that ships its own\nLexical is counted there too; it is evidence of a bug only when those editors\nwere supposed to be part of *your* app.\n\nSilent failures look like: a command that dispatches but never fires its\nlistener, `$getSelection()` returning `null` inside an update, or a custom node\nrendering as plain text after a copy/paste. Real reports of this failure mode:\n[#4225](https://github.com/facebook/lexical/issues/4225) and\n[#7819](https://github.com/facebook/lexical/issues/7819).\n\n## Publishing a library\n\nIf you publish a package that imports from `lexical` or `@lexical/*` — a plugin,\na node package, a shared editor config, an in-house wrapper in a monorepo — put\nthose packages in `peerDependencies`, and in `devDependencies` so you can still\nbuild and test:\n\n```json\n{\n \"name\": \"my-lexical-plugin\",\n \"peerDependencies\": {\n \"lexical\": \">=0.50.0\",\n \"@lexical/react\": \">=0.50.0\",\n \"@lexical/utils\": \">=0.50.0\"\n },\n \"devDependencies\": {\n \"lexical\": \"0.50.0\",\n \"@lexical/react\": \"0.50.0\",\n \"@lexical/utils\": \"0.50.0\"\n }\n}\n```\n\nNotes on the ranges:\n\n- Lexical is pre-1.0, so `^0.50.0` means `>=0.50.0 <0.51.0` — a caret peer range\n locks your users out of the next release. Prefer an open `>=` range (or an\n explicit `>=0.50.0 <1.0.0`) so an app can upgrade Lexical without waiting for\n you.\n- Mark a peer optional with\n [`peerDependenciesMeta`](https://docs.npmjs.com/cli/configuring-npm/package-json#peerdependenciesmeta)\n when the import is behind an opt-in entry point, the way this repo's own\n packages mark `typescript` optional.\n- Do not add `lexical` to `dependencies` \"just so it installs\". That is exactly\n what pins a second copy under `node_modules/your-lib/node_modules/lexical` as\n soon as your range and the app's range disagree.\n\n## Application setup\n\nThe application owns the version, and every Lexical package it installs moves\ntogether:\n\n- Install `lexical` and each `@lexical/*` package you use **at the same\n version**. Published `@lexical/*` packages depend on the exact matching\n `lexical` version (the monorepo's `workspace:*` is rewritten to an exact\n version at publish time), so `@lexical/react@0.50.0` beside `lexical@0.49.0`\n guarantees a nested second copy.\n- Verify there is only one **per app**, from the app root:\n\n ```sh\n npm ls lexical @lexical/react # or: pnpm why lexical / yarn why lexical\n ```\n\n More than one resolved version, or a path with a nested `node_modules/lexical`\n in it, is the bug.\n- In a monorepo or a linked-package setup (`npm link`, `pnpm link`, a Yalc\n copy), the linked library resolves Lexical from *its own* `node_modules` and\n duplicates are the default rather than the exception. Deduplicate explicitly:\n hoist the dependency to the workspace root, or force resolution with\n [pnpm `overrides`](https://pnpm.io/settings#overrides), Yarn `resolutions`, or\n `npm dedupe`.\n- Bundlers can also be told to collapse duplicates — Vite\n [`resolve.dedupe`](https://vite.dev/config/shared-options.html#resolve-dedupe),\n webpack `resolve.alias` pointing each package at one path:\n\n ```js\n // vite.config.js\n export default {\n resolve: {dedupe: ['lexical', '@lexical/react', '@lexical/utils']},\n };\n ```\n\n Treat that as a safety net, not a fix: it collapses copies that are already\n version-compatible, and cannot rescue two genuinely different versions.\n- Duplication does not always come from the dependency tree: importing Lexical\n through both `import` and `require` pulls in the ESM and the CJS build of the\n *same* version, which are still two copies. The\n [React FAQ](../react/faq.md#lexicalcomposercontextuselexicalcomposercontext-cannot-find-a-lexicalcomposercontext)\n covers how this one shows up in `@lexical/react`.\n","packages/lexical-website/docs/concepts/read-only.md":"\n\n# Read Mode / Edit Mode\n\nLexical supports two modes:\n\n- Read mode\n- Edit mode\n\nThe default behavior for Lexical is edit mode, or more accurately not read only mode. Under-the-hood, the main\nimplementation detail is that the `contentEditable` is being set to `\"false\"` or `\"true\"` depending on the mode.\nSpecific plugins can listen to the mode change too – allowing them to customize parts of the UI depending on the\nmode.\n\n## Setting the mode\n\nIn order to set the mode, this can be done on creation of the editor, with the\n`editable` property of your app's extension:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [RichTextExtension],\n editable: false,\n name: '@my-app/editor',\n }),\n);\n```\n\nWith React, pass the same extension to ``:\n\n```jsx\n\n ...\n\n```\n\nAfter an editor is created, the mode can be changed imperatively:\n\n```js\neditor.setEditable(true);\n```\n\n## Reading the mode\n\nIn order to find the current mode of the editor you can use:\n\n```js\nconst isEditable = editor.isEditable(); // Returns true or false\n```\n\nYou can also get notified when the editor's read only mode has changed:\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (isEditable) => {\n // The editor's mode is passed in!\n console.log(isEditable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\nIn an extension, depend on\n[`WatchEditableExtension`](/docs/api/modules/lexical_extension#watcheditableextension),\nwhose output is a signal holding the current editable state, instead of\nregistering the listener yourself.\n","packages/lexical-website/docs/concepts/selection.md":"# Selection\n\n## Types of selection\n\nLexical's selection is part of the `EditorState`. This means that for every update, or change to the editor, the\nselection always remains consistent with that of the `EditorState`'s node tree.\n\nIn Lexical, there are four types of selection possible:\n\n- `RangeSelection`\n- `NodeSelection`\n- `TableSelection` (implemented in `@lexical/table`)\n- `null`\n\nIt is possible, but not generally recommended, to implement your own selection types that implement `BaseSelection`.\n\n### `RangeSelection`\n\nThis is the most common type of selection, and is a normalization of the browser's DOM Selection and Range APIs.\n`RangeSelection` consists of three main properties:\n\n- `anchor` representing a `RangeSelection` point\n- `focus` representing a `RangeSelection` point\n- `format` numeric bitwise flag, representing any active text formats\n\nBoth the `anchor` and `focus` points refer to an object that represents a specific part of the editor. The main properties of a `RangeSelection` point are:\n\n- `key` representing the `NodeKey` of the selected Lexical node\n- `offset` representing the position from within its selected Lexical node. For the `text` type this is the character, and for the `element` type this is the child index from within the `ElementNode`\n- `type` representing either `element` or `text`.\n\n### `NodeSelection`\n\nNodeSelection represents a selection of multiple arbitrary nodes. For example, three images selected at the same time.\n\n- `getNodes()` returns an array containing the selected LexicalNodes\n\n### `TableSelection`\n\nTableSelection represents a grid-like selection like tables. It stores the key of the parent node where the selection takes place and the start and end points.\n`TableSelection` consists of three main properties:\n\n- `tableKey` representing the parent node key where the selection takes place\n- `anchor` representing a `TableSelection` point\n- `focus` representing a `TableSelection` point\n\nFor example, a table where you select row = 1 col = 1 to row 2 col = 2 could be stored as follows:\n- `tableKey = 2` table key\n- `anchor = 4` table cell (key may vary)\n- `focus = 10` table cell (key may vary)\n\nNote that `anchor` and `focus` points work the same way as `RangeSelection`.\n\n### `null`\n\nThis is for when the editor doesn't have any active selection. This is common for when the editor has been blurred or when selection\nhas moved to another editor on the page. This can also happen when trying to select non-editable components within the editor space.\n\n## Working with selection\n\nSelection can be found using the `$getSelection()` helper, exported from the `lexical` package. This function can be used within\nan update, a read, or a command listener.\n\n:::tip\n\nTo walk the document from a selection point — or to write a traversal that\nhandles empty nodes and collapsed selections correctly — see\n[Node Traversals with NodeCaret](./traversals.md).\n`$caretRangeFromSelection(selection)` converts a `RangeSelection` into the\ncaret range that traversal API works with, and\n`$setSelectionFromCaretRange(range)` converts back.\n\n:::\n\n```js\nimport {$getSelection, SELECTION_CHANGE_COMMAND} from 'lexical';\n\neditor.update(() => {\n const selection = $getSelection();\n});\n\neditorState.read(() => {\n const selection = $getSelection();\n});\n\n// SELECTION_CHANGE_COMMAND runs before reconciliation in the pending update.\neditor.registerCommand(SELECTION_CHANGE_COMMAND, () => {\n const selection = $getSelection();\n});\n```\n\nIn some cases you might want to create a new type of selection and set the editor selection to\nbe that. This can only be done in update or command listeners.\n\n```js\nimport {$setSelection, $createRangeSelection, $createNodeSelection} from 'lexical';\n\neditor.update(() => {\n // Set a range selection\n const rangeSelection = $createRangeSelection();\n $setSelection(rangeSelection);\n\n // You can also indirectly create a range selection, by calling some of the selection\n // methods on Lexical nodes.\n const someNode = $getNodeByKey(someKey);\n\n // On element nodes, this will create a RangeSelection with type \"element\",\n // referencing an offset relating to the child within the element.\n // On text nodes, this will create a RangeSelection with type \"text\",\n // referencing the text character offset.\n someNode.select();\n someNode.selectPrevious();\n someNode.selectNext();\n\n // You can use this on any node.\n someNode.selectStart();\n someNode.selectEnd();\n\n // Set a node selection\n const nodeSelection = $createNodeSelection();\n // Add a node key to the selection.\n nodeSelection.add(someKey);\n $setSelection(nodeSelection);\n\n // You can also clear selection by setting it to `null`.\n $setSelection(null);\n});\n```\n\n## Focus\n\nYou may notice that when you issue an `editor.update` or\n`editor.dispatchCommand` then the editor can \"steal focus\" if there is\na selection and the editor is editable. This is because the Lexical\nselection is reconciled to the DOM selection during reconciliation,\nand the browser's focus follows its DOM selection.\n\nIf you want to make updates or dispatch commands to the editor without\nchanging the selection, can use the `SKIP_DOM_SELECTION_TAG` update tag\n(added in v0.22.0):\n\n```js\n// Call this from an editor.update or command listener\n$addUpdateTag(SKIP_DOM_SELECTION_TAG);\n```\n\nIf you want to add this tag during processing of a `dispatchCommand`,\nyou can wrap it in an `editor.update`:\n\n```js\n// NOTE: If you are already in a command listener or editor.update,\n// do *not* nest a second editor.update! Nested updates have\n// confusing semantics (dispatchCommand will re-use the\n// current update without nesting)\neditor.update(() => {\n $addUpdateTag(SKIP_DOM_SELECTION_TAG);\n editor.dispatchCommand(/* … */);\n});\n```\n\n`SKIP_DOM_SELECTION_TAG` does not apply to the initial editor state setup\n(the `$initialEditorState` property of the root extension, or\n`initialConfig.editorState` with the legacy `LexicalComposer`). On first mount the editor still scrolls\nto and focuses the initial selection. To prevent that, call\n`$setSelection(null)` inside your initial state setup function:\n\n```js\nconst editor = buildEditorFromExtensions({\n name: '[root]',\n // ...\n $initialEditorState: () => {\n // ... build your initial nodes ...\n $setSelection(null);\n },\n});\n```\n\nIf you have to support older versions of Lexical, you can mark the editor\nas not editable during the update or dispatch.\n\n```js\n// NOTE: This code should be *outside* of your update or command listener, e.g.\n// directly in the DOM event listener\nconst prevEditable = editor.isEditable();\neditor.setEditable(false);\neditor.update(\n () => {\n // run your update code or editor.dispatchCommand in here\n }, {\n onUpdate: () => {\n editor.setEditable(prevEditable);\n },\n },\n);\n```\n\n## Reading selection across a shadow boundary\n\nIf your plugin reads the DOM selection directly — through\n`Selection.anchorNode`, `Selection.getRangeAt(0)`, or similar — and the\neditor's `contentEditable` lives inside a `ShadowRoot`, the browser retargets\nthose reads to the shadow host. See\n[Shadow DOM and iframes](./shadow-dom.md) for the shadow-aware helpers\n(`getDOMSelectionPoints`, `getDOMSelectionRange`, etc.) that return the\nun-retargeted boundary points; they fall through to the standard reads in the\nplain light DOM, so there's nothing to do until you actually mount the editor\nin a shadow tree.\n\n### Selection change timing\n\n`SELECTION_CHANGE_COMMAND` runs **before reconciliation**, in a writable update,\nfor native, programmatic, and non-range selection changes. `$getSelection()`\nreturns the pending selection; `$getPreviousSelection()` returns the selection\nfrom the last committed state. A listener can normalize the selection or edit\nnodes before that same update commits. Listeners that change the selection may\ncause another notification before commit; they must converge.\n\nThis covers programmatic changes such as `node.select()`, which notify without\nwaiting for a DOM `selectionchange` event, and non-range selections such as\n`NodeSelection` and `TableSelection`, as well as native range selections.\n\nSelection listeners use the update's normal error handling. A throwing listener\nreports through `onError` and can abort the entire pending update, including the\nedit that triggered the notification and any other edits batched into that\ncommit, just like an explicit command dispatch inside that update. Because a\nprogrammatic selection change also notifies, a listener error can abort content\nedits made in the same update. Listener edits do not have a separate rollback\nscope.\n\nThe DOM is not guaranteed to match the pending state, even for a `NodeSelection`.\nNew nodes may not have an element yet, and DOM ranges, layout, and focus may\nstill reflect the previous state. Schedule DOM-dependent work after the update\nand read the reconciled state there:\n\n```ts\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n $onUpdate(() => {\n editor.read('latest', () => {\n // Read $getSelection(), look up elements, or position floating UI here.\n });\n });\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport `$onUpdate` and `COMMAND_PRIORITY_LOW` from `lexical`. Read selection and\nnodes inside the callback rather than capturing mutable pending objects.\n`registerUpdateListener` is another option for UI that must respond to every\ncommit, including content changes that do not change the selection. Updates\nusing `SKIP_DOM_SELECTION_TAG` still deliberately leave the browser selection\nunsynchronized.\n\n#### Update tags and local edits\n\nThe notification belongs to the pending update and inherits its tags. A listener\ncan inspect them with `$hasUpdateTag`. In particular, Yjs does not sync content\nedits back to peers when the update is tagged `COLLABORATION_TAG` or\n`HISTORIC_TAG`; history also treats `HISTORIC_TAG` as replaying an existing entry.\nThis applies to content edits made by selection listeners in those updates.\n\nListeners that only apply to local editing should skip those tagged updates. If\na remote change or undo must trigger an independent local content edit, schedule\nit after the tagged commit with `$onUpdate`, then start a fresh `editor.update`:\n\n```ts\nconst $applyLocalEdit = () => {\n // Read the current selection and nodes, then apply a convergent local edit.\n};\n\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n if ($hasUpdateTag(COLLABORATION_TAG) || $hasUpdateTag(HISTORIC_TAG)) {\n $onUpdate(() => editor.update($applyLocalEdit));\n } else {\n $applyLocalEdit();\n }\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport the tags and `$hasUpdateTag` from `lexical`. Re-read the state in the fresh\nupdate; it has its own collaboration and undo behavior. Calling `editor.update`\ndirectly inside the command listener queues a nested update that still belongs\nto the same tagged commit.\n\nAutomatic range and cleared-selection notifications require a connected editor\nroot. Changes committed while those notifications are skipped advance the\nselection baseline and are not replayed when the root reconnects. Non-range\nselections continue to notify in unmounted and headless editors,\nwith the same pre-reconciliation timing. Native dirty-selection notifications\nmay fire even when the selection compares equal to the previous selection.\n","packages/lexical-website/docs/concepts/shadow-dom.md":"---\nsidebar_label: Shadow DOM and iframes\n---\n\n# Shadow DOM and iframes\n\nA Lexical editor works when its `contentEditable` lives inside an **open**\n[DOM `ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) (for\nexample inside a [web component](https://developer.mozilla.org/docs/Web/API/Web_components))\nor inside an `\n\n## Sharing one Yjs document between editors\n\nBy default a binding uses the `XmlText` shared type named `root` on the Yjs\n`Doc`, so each editor needs its own document. Two options let several editors\nlive in one document instead, which is what applications like collaborative\nsticky notes or comment threads usually want:\n\n- `rootName` picks a different top-level shared type, one per editor:\n\n```jsx\n\n```\n\n- `getXmlText` resolves the root yourself, for roots that are not top-level\n shared types (for example an `XmlText` stored in a `Y.Map`). It takes\n precedence over `rootName`:\n\n```jsx\nconst getXmlText = useCallback(\n (doc) => doc.getMap('notes').get(noteId),\n [noteId],\n);\n\n\n```\n\nGive each editor its own `id`, as above: the `id` keys the document map and the\nremote-cursor highlight registry, both of which are shared across the page, so\ntwo editors mounted under one `id` overwrite each other's entries.\n\nBoth options are also available on `createYjsBinding` for non-React usage.\n\n:::warning\n\nThe root is chosen when the binding is created, and a mounted editor cannot be\nrepointed at another root: changing `rootName` or `getXmlText` afterwards has no\neffect. To switch documents, remount the **editor** — put a `key` that changes\nwith the document on the component that owns the `LexicalComposer`. Remounting\nonly the plugin is not enough: the editor would keep the previous document's\ncontent and write it into the newly selected root.\n\n:::\n\n`getXmlText` runs while the binding is constructed, before the provider has\nsynced, so it has to resolve the root from whatever the local `Doc` holds at\nthat moment — reaching into a `Y.Array` that the server has not sent yet throws.\nEither mount the editor only once the note exists locally, or have the callback\ncreate the missing shared type. Write it to be idempotent: it can run more than\nonce for one editor (React StrictMode double-invokes render, and a remount\nbuilds a new binding), and a callback that unconditionally stores a new\n`XmlText` would throw away what the previous call stored.\n\nThe returned `XmlText` is checked to be an `XmlText` that is integrated into the\ndocument; that it is not already driving another live binding is yours to\nguarantee, since a second binding over one root takes over the collab nodes\ncached on its shared types.\n\nThe experimental `CollaborationPluginV2__EXPERIMENTAL` (and\n`createBindingV2__EXPERIMENTAL`) take the same two options, except that its\nroot is an `XmlElement`, so the callback is named `getXmlElement`. Create that\nelement as `new Y.XmlElement()` without a `nodeName`, which is how the root is\nrecognized.\n\n## Building collaborative plugins\n\n[Lexical Playground](https://playground.lexical.dev/) features set of the collaboration enabled plugins that integrate with primary document via `useCollaborationContext()` hook. Notable mentions:\n\n- [`CommentPlugin`](https://github.com/facebook/lexical/tree/main/packages/lexical-playground/src/plugins/CommentPlugin) - features use of the separate provider and Yjs room to sync comments.\n- [`ImageComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/ImageComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested caption editor.\n- [`PollOptionComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/PollComponent.tsx) - showcases poll implementation using `name` from the collaboration context.\n- [`StickyComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/StickyComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested editor as well as sticky note position real-time sync.\n\n:::note\n\nWhile these \"playground\" plugins aren't production ready - they serve as a great example of collaborative Lexical capabilities as well as provide a good starting point.\n\n:::\n\n## Custom node property syncing\n\n`@lexical/yjs` syncs custom node properties by constructing a fresh node instance and inspecting its **own enumerable properties**. This means every property that should be synced across peers must be assigned in the constructor, even if the initial value is `undefined`.\n\n:::warning\n\nDeclaring a class property with TypeScript's optional syntax (`foo?: Type`) does **not** guarantee the property exists as an own enumerable property on the instance. Under TypeScript's default compilation settings (target < ES2022 without `useDefineForClassFields`), such declarations produce no initialization code.\n\n:::\n\n### What to do\n\nAlways initialize every node property in the constructor. Conditional initialization such as `if (someValue !== undefined) this.__someValue = someValue` is not enough, because the default construction path still needs to create the property.\n\nFor example:\n\n```ts\n// ✅ Correct — property is guaranteed to be an own property\nclass MyNode extends ElementNode {\n __someValue: string | undefined;\n\n constructor(someValue?: string, key?: NodeKey) {\n super(key);\n this.__someValue = someValue; // explicitly initialized\n }\n}\n\n// ❌ Incorrect — property may not exist as an own property\nclass MyNode extends ElementNode {\n __someValue?: string; // optional syntax without initialization\n\n constructor(key?: NodeKey) {\n super(key);\n // __someValue is never assigned → won't be synced via yjs\n }\n}\n```\n\nIf you use [`NodeState`](../concepts/node-state.md) for your custom properties, this concern does not apply. `NodeState` values are synced correctly without relying on constructor-created enumerable properties.\n\n## Yjs providers\n\nSetting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. Providers manage all that for you and are the perfect starting point for your collaborative app.\n\nSee [Yjs Website](https://docs.yjs.dev/ecosystem/connection-provider) for the list of the officially endorsed providers. Although it's not an exhaustive one.\n","packages/lexical-website/docs/concepts/_category_.json":"{\n \"label\": \"Concepts\",\n \"position\": 3\n}\n","packages/lexical-website/docs/concepts/commands.md":"\n\n# Commands\n\nCommands are a very powerful feature of Lexical that lets you register listeners for events like `KEY_ENTER_COMMAND` or `KEY_TAB_COMMAND` and contextually react to them _wherever_ & _however_ you'd like.\n\nThis pattern is useful for building [`Toolbars`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) or complex extensions and nodes such as [tables](https://github.com/facebook/lexical/tree/main/packages/lexical-table) which require special handling for `selection`, `keyboard events`, and more.\n\nWhen registering a `command` you supply a `priority` and can return `true` to mark it as \"handled\", which stops other listeners from receiving the event. If a command isn't handled explicitly by you, it's likely handled by default in [`RichTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-rich-text/src/index.ts) or [`PlainTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-plain-text/src/index.ts).\n\n## `createCommand(...)`\n\nYou can view the core commands in the [`lexical` API reference](/docs/api/modules/lexical#commands). Other packages define their own, listed under Commands in each package's API reference, such as [`TOGGLE_LINK_COMMAND`](/docs/api/modules/lexical_link#toggle_link_command) in `@lexical/link`. If you need a custom command for your own use case, check out the typed `createCommand(...)` function.\n\n```js\nconst HELLO_WORLD_COMMAND: LexicalCommand = createCommand('HELLO_WORLD');\n\neditor.registerCommand(\n HELLO_WORLD_COMMAND,\n (payload: string) => {\n console.log(payload); // Hello World!\n return false;\n },\n COMMAND_PRIORITY_EDITOR,\n);\n\neditor.dispatchCommand(HELLO_WORLD_COMMAND, 'Hello World!');\n```\n\n## `editor.dispatchCommand(...)`\n\nCommands can be dispatched from anywhere you have access to the `editor` such as a Toolbar Button, an event listener, or an extension, but most of the core commands are dispatched from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\nCalling `dispatchCommand` will implicitly call `editor.update` to trigger its command listeners if it was not called from inside `editor.update`.\n\nDon't dispatch a command from inside a read-only context such as\n`editor.read(fn)` or `editorState.read(fn)`. Command listeners usually change\nthe editor, so Lexical runs them in a separate writable update and\ndevelopment builds log a warning when they detect this. Dispatch after the\nread returns instead.\n\n```js\neditor.dispatchCommand(command, payload);\n```\n\nThe `payload`s are typed via the `createCommand(...)` API, but they're usually a DOM `event` for commands dispatched from an event listener.\n\nHere are some real examples from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\n```js\neditor.dispatchCommand(KEY_ARROW_LEFT_COMMAND, event);\n// ...\neditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic');\n```\n\nAnd another example from the [`ToolbarPlugin`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) in our Playground.\n\n```js\nconst formatBulletList = () => {\n editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND);\n};\n```\n\nWhich is later handled by [`ListExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-list/src/LexicalListExtension.ts) to insert the list into the editor.\n\n```js\neditor.registerCommand(\n INSERT_UNORDERED_LIST_COMMAND,\n () => {\n $insertList('bullet');\n return true;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\n## `editor.registerCommand(...)`\n\nYou can register a command from anywhere you have access to the `editor` object, but it's important that you remember to clean up the listener with its remove listener callback when it's no longer needed.\n\nThe command listener will always be called from an `editor.update`, so you may use dollar functions. You should not use\n`editor.update` (and *never* call `editor.read(...)` or `editor.read('force-commit', ...)`) synchronously from within a command listener. It is safe to call\n`editor.read('latest', ...)` or `editor.getEditorState().read` if you need to read the previous state after updates have already been made.\n\n```js\nconst removeListener = editor.registerCommand(\n COMMAND,\n (payload) => boolean, // Return true to stop propagation.\n priority,\n);\n// ...\nremoveListener(); // Cleans up the listener.\n```\n\nThe easiest way to get clean-up right is to register commands from an\n[extension](/docs/extensions/defining-extensions)'s `register` function and\nreturn the remove callback. The editor calls it when it is disposed. To\nregister several things, combine their callbacks with `mergeRegister` from\n`@lexical/utils`.\n\n```js\nimport {LinkExtension, TOGGLE_LINK_COMMAND} from '@lexical/link';\nimport {COMMAND_PRIORITY_BEFORE_EDITOR, defineExtension} from 'lexical';\n\nexport const LinkLoggerExtension = defineExtension({\n // The command it observes is handled by LinkExtension\n dependencies: [LinkExtension],\n name: '@my-app/LinkLogger',\n register: (editor) =>\n editor.registerCommand(\n TOGGLE_LINK_COMMAND,\n (payload) => {\n console.log('link', payload);\n return false; // let the link extension handle it too\n },\n // LinkExtension handles this command at COMMAND_PRIORITY_EDITOR and\n // returns true, so observe it at the BEFORE variant of that priority.\n COMMAND_PRIORITY_BEFORE_EDITOR,\n ),\n});\n```\n\nA listener that only observes a command, like this one, needs to run before\nthe listener that handles it. Depending on the extension that handles it and\nusing the `COMMAND_PRIORITY_BEFORE_*` variant of its priority does that\nwithout escalating to a higher priority. See\n[Priorities and ordering](#priorities-and-ordering) below.\n\nIn a legacy React plugin, return the `registerCommand` call from a\n`useEffect` instead.\n\nAnd as seen above and below, `registerCommand`'s callback can return `true` to signal to the other listeners that the command has been handled and propagation will be stopped.\n\nHere's a simplified example of handling a `KEY_TAB_COMMAND` from [`TabIndentationExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-extension/src/TabIndentationExtension.ts), which is used to dispatch a `OUTDENT_CONTENT_COMMAND` or `INDENT_CONTENT_COMMAND`.\n\n```js\neditor.registerCommand(\n KEY_TAB_COMMAND,\n (payload) => {\n const event: KeyboardEvent = payload;\n event.preventDefault();\n return editor.dispatchCommand(\n event.shiftKey ? OUTDENT_CONTENT_COMMAND : INDENT_CONTENT_COMMAND,\n );\n },\n COMMAND_PRIORITY_EDITOR,\n);\n```\n\nNote that the same `KEY_TAB_COMMAND` command is registered by [`LexicalTableSelectionHelpers.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical-table/src/LexicalTableSelectionHelpers.ts), which handles moving focus to the next or previous cell within a `TableNode`, but the priority is high (`COMMAND_PRIORITY_HIGH`) because this behavior is very important.\n\n### Priorities and ordering\n\nCommand listeners are called in the following order until a listener returns `true`:\n\n- From priority highest to lowest (critical, high, normal, low, editor)\n- All `COMMAND_PRIORITY_BEFORE_${priority}` listeners, most recently registered first\n- All `COMMAND_PRIORITY_${priority}` listeners, in registration order\n\n:::note\n\nThe `COMMAND_PRIORITY_BEFORE_*` priorities make it much easier to override\ndefault behavior without escalating the priority.\n\n:::\n\nIt is best practice to use the lowest priority possible, so most commands will\nbe registered with `COMMAND_PRIORITY_EDITOR` for the default behavior, then\ncommands to override that behavior can be registered with\n`COMMAND_PRIORITY_BEFORE_EDITOR`. The higher priorities mostly serve purposes\nsuch as being able to observe-but-not-handle events and to support legacy code\nthat predates the availability of `COMMAND_PRIORITY_BEFORE_*`.\n\nA modern lexical app will typically only need the\n`COMMAND_PRIORITY_BEFORE_EDITOR` priority since the\nlast-registered-called-first ordering is suitable for almost all use cases. The\nolder priorities without BEFORE can be considered legacy and are primarily\noffered for compatibility.\n\nHere is the full ordering of priorities, from lowest to highest:\n\n- `COMMAND_PRIORITY_EDITOR`\n- `COMMAND_PRIORITY_BEFORE_EDITOR`\n- `COMMAND_PRIORITY_LOW`\n- `COMMAND_PRIORITY_BEFORE_LOW`\n- `COMMAND_PRIORITY_NORMAL`\n- `COMMAND_PRIORITY_BEFORE_NORMAL`\n- `COMMAND_PRIORITY_HIGH`\n- `COMMAND_PRIORITY_BEFORE_HIGH`\n- `COMMAND_PRIORITY_CRITICAL`\n- `COMMAND_PRIORITY_BEFORE_CRITICAL`\n","packages/lexical-website/docs/concepts/compared-with-prosemirror.md":"# Compared with ProseMirror\n\nLexical and [ProseMirror](https://prosemirror.net) are both frameworks for\nbuilding rich text editors on top of `contentEditable`, and both keep an\nimmutable document model as the source of truth. This page collects the main\ndifferences in one place, for readers who know one and are learning the other.\n\n## Document model {#document-model}\n\nLexical's tree is shaped like the HTML it renders (see\n[Document Model](./document-model.md)). This is a deliberate difference from\nProseMirror. ProseMirror's document is also a tree,\nand blocks can contain other blocks, but the inline content of a textblock is\na flat sequence of nodes (text and inline nodes) with marks for formatting and\nlinks, and every position in the document is a single integer.\n\n| | Lexical | ProseMirror |\n| -- | -- | -- |\n| Document | Immutable tree of nodes, one `RootNode` | Immutable tree of nodes, one `doc` node |\n| Node identity and navigation | Each node has a runtime key and knows its parent and siblings | Nodes are plain values with no parent links; a resolved position supplies ancestor context |\n| Blocks | `ElementNode` subclasses (paragraph, heading, list, table, …), or a block `DecoratorNode` (image, embed, …) | Block nodes defined in the schema |\n| Inline formatting | Format flags on each `TextNode` (bold, italic, code, …) | Marks on text |\n| Links and other inline wrappers | Inline `ElementNode`s (`LinkNode`, `MarkNode`) that contain text nodes | Marks on text, like formatting |\n| Embedded content | `DecoratorNode`, inline or block, rendered by your framework (for example React) | Leaf or atom nodes, often with a custom `NodeView` |\n| Several editable regions in one node | [Named slots](./named-slots.md): regions addressed by name, like a card's `title`, each isolated so editing and selection never cross the boundary | Child nodes in the order the schema's content expression allows, optionally marked `isolating`, or a separate editor inside a `NodeView` |\n| Addressing a position | Node key plus offset (`{key, offset, type}`) | One integer counted across the whole document |\n| Allowed structure | Declared by node classes, enforced with node transforms and normalization | Declared by a schema of content expressions |\n| Applying edits | Call node and selection methods inside `editor.update()` | Build a transaction from steps that address positions or ranges |\n| Rendering | Each node's `createDOM()`/`updateDOM()`, applied by the reconciler, and optionally changed per node class by a `DOMRenderExtension` override | `toDOM` in the schema, or a `NodeView` |\n\n## Serialization {#serialization}\n\nBecause a Lexical link is an element that already contains its text, it\nexports as an `` around those text nodes. A mark-based model has to find the\nadjacent text that shares a mark and group it into one element first.\n\n| Format | Lexical | ProseMirror |\n| -- | -- | -- |\n| JSON | `editorState.toJSON()`, restored with `editor.parseEditorState()` | `doc.toJSON()` and `Node.fromJSON(schema, json)` |\n| HTML export | `$generateHtmlFromNodes()`, using each node's `createDOM()` or `exportDOM()` | `DOMSerializer.fromSchema(schema)`, using `toDOM` from the schema's nodes and marks |\n| HTML import | `$generateNodesFromDOM()`, using `importDOM()` or `DOMImportExtension` rules | `DOMParser.fromSchema(schema)`, using the schema's `parseDOM` rules |\n| Markdown | `@lexical/markdown` transformers or `@lexical/mdast` | `prosemirror-markdown`: a markdown-it parser and a serializer with a function per node and mark |\n| Clipboard | Copy writes plain text, HTML, and Lexical JSON. Paste prefers the JSON, then HTML, then plain text. | Copy writes HTML and plain text. Paste parses the HTML with the schema's parse rules. |\n\nIn the JSON, a Lexical link is a `link` node with its text nodes as\n`children`, and bold is a `format` value on a `text` node, where\nProseMirror's JSON gives each text node a list of `marks`. In both editors the\ndefault HTML export reuses the definition that renders the editor\n(`createDOM()` in Lexical, `toDOM` in ProseMirror), so the two stay in step\nunless you override one. See [Serialization](../serialization/serialization.md)\nfor the details of each Lexical format.\n\n## History {#history}\n\nBoth editors group consecutive edits into one undo step. Lexical's\n[`HistoryExtension`](./history.md) merges edits made within `delay`\n(300ms by default) and keeps an unlimited stack unless you set `maxDepth`.\nProseMirror's history plugin uses `newGroupDelay: 500` and `depth: 100` by\ndefault, so `configExtension(HistoryExtension, {delay: 500, maxDepth: 100})`\nmatches its behavior.\n","packages/lexical-website/docs/concepts/document-model.md":"# Document Model\n\nAn [editor state](./editor-state.md) holds a tree of nodes. This page explains\nhow that tree is shaped.\n\n## A DOM-like tree\n\nLexical's node tree is shaped like the HTML it renders. A paragraph is an\n`ElementNode` whose children are the nodes inside it, and inline structure\nnests the same way: a link is a `LinkNode` element that contains the text\nnodes it wraps, just as an `` contains its text. Each node type decides how\nit renders with `createDOM()` and `updateDOM()`, so the model maps closely to\nthe DOM, and a position in the document is a node plus an offset within it.\n\nHere is a small document with a heading, a paragraph containing bold text and\na link, a block image, and a card that has a named `title` slot as well as\nordinary body children:\n\n```mermaid\nflowchart TB\n accTitle: The shape of a Lexical document tree\n accDescr: The root has four children in order: a heading, a paragraph, an image, and a card. The heading contains the text \"Welcome\". The paragraph contains the text \"Read the \", a bold text node \"docs\", and a link, which contains the text \"here\". The image is a block decorator node with no children. The card has a named slot called title, which holds a paragraph containing the text \"Card title\", and one ordinary child, a paragraph containing the text \"Card body\".\n root[\"Root\"] --> heading[\"Heading (h1)\"]\n root --> paragraph[\"Paragraph\"]\n root --> image[\"Image
(block DecoratorNode)\"]\n root --> card[\"Card
(ElementNode)\"]\n heading --> welcome[\"Text: 'Welcome'\"]\n paragraph --> read[\"Text: 'Read the '\"]\n paragraph --> docs[\"Text: 'docs'
{ format: bold }\"]\n paragraph --> link[\"Link\"]\n link --> here[\"Text: 'here'\"]\n card -.->|\"slot: title\"| titlePara[\"Paragraph\"]\n titlePara --> titleText[\"Text: 'Card title'\"]\n card --> body[\"Paragraph\"]\n body --> bodyText[\"Text: 'Card body'\"]\n```\n\nSolid arrows are ordinary children, which form an ordered list under their\nparent and are read with `getChildren()`. The dashed arrow is a\n[named slot](./named-slots.md): a separate channel on the host, keyed by name\ninstead of position and read with `$getSlot(card, 'title')`. A slot's value\nis the root of its own isolated region, so its `getParent()` is `null` and\n`$getSlotHost()` leads back to the card. Any `ElementNode` or `DecoratorNode`\ncan host slots, so a decorator such as the image could also expose an\neditable caption this way.\n\n## Working with the tree\n\nLexical code navigates the document the way DOM code does, with methods like\n`getParent()`, `getChildren()`, and `getNextSibling()`, and each node owns the\nDOM it renders. The resemblance is structural, not one\nnode per HTML element: bold or italic text, for example, is a format on a\n`TextNode`, not a separate `` or `` node. See\n[Nodes](./nodes.mdx) for the built-in node types.\n\n## Customizing rendering\n\nYou can also change how nodes render without subclassing them.\n[`DOMRenderExtension`](../serialization/dom-render.md) from `@lexical/html`\ntakes overrides for `createDOM`, `updateDOM`, and `exportDOM`, for one node\nclass or for every node, such as adding a `data-` attribute or wrapping a\nnode's children in another element. Each override calls `$next()` to get the\ndefault result and adjusts it, so overrides from several extensions compose.\nExport overrides only affect HTML export, and `createDOM` overrides also carry\nthrough to export for nodes that use the default `exportDOM`. Changes made\nwhile updating the editor's DOM don't; see\n[Lexical -> HTML](../serialization/serialization.md#lexical---html) for which\nhooks reach export.\n\nFor how the tree is converted to and from JSON, HTML, and Markdown, see\n[Serialization](../serialization/serialization.md#formats-at-a-glance). For\nhow this model differs from a mark-based editor, see\n[Compared with ProseMirror](./compared-with-prosemirror.md).\n","packages/lexical-website/docs/concepts/dom-events.md":"\n\n# Working with DOM Events\n\nSometimes, when working with Lexical, it might be necessary or useful for you to attach a DOM Event Listener to the underlying DOM nodes that Lexical controls. For instance, you might want to show a popover when a user mouses over a specific node or open a modal when they click on a node. Either of these use cases (and many others) can be accomplished via native DOM Event Listeners. There are 3 main ways that you can listen for DOM Events on nodes controlled by Lexical:\n\n## 1. Event Delegation\n\nOne way to handle events inside the editor is to set a listener on the editor root element (the contentEditable Lexical attaches to). You can do this using a [Root Listener](listeners.md).\n\n```js\nfunction myListener(event) {\n // You may want to filter on the event target here\n // to only include clicks on certain types of DOM Nodes.\n alert('Nice!');\n}\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) => {\n if (rootElement === null) {\n return;\n }\n // add the listener to the current root element\n rootElement.addEventListener('click', myListener);\n // remove the listener when the root element changes - make sure the ref\n // to myListener is stable so the removal works and you avoid a memory leak.\n return () => rootElement.removeEventListener('click', myListener);\n }),\n});\n```\n\nAn extension's `register` returns a cleanup function, and the editor calls it\nwhen it is disposed, so there is no teardown to write by hand. Add\n`ClickExtension` to your editor's `dependencies` to use it.\nThis can be a simple, efficient way to handle some use cases, since it's not necessary to attach a listener to each DOM node individually.\n\nThe `addEventListener`/`removeEventListener` pairing above is common enough that the core `lexical` package exports a `registerEventListener(target, type, listener, options?)` helper. It attaches the listener and returns a dispose function that removes it, so the example above becomes:\n\n```js\nimport {defineExtension, registerEventListener} from 'lexical';\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) =>\n // registerEventListener returns the matching removeEventListener cleanup,\n // so there's no need to write the teardown by hand.\n rootElement === null\n ? undefined\n : registerEventListener(rootElement, 'click', myListener),\n ),\n});\n```\n\nIt mirrors the `addEventListener` overloads (so the event type is strongly typed) and composes well with `mergeRegister` when you need to register several listeners at once.\n\nTo attach several listeners to the same target, `registerEventListeners(target, listeners, options?)` takes a `{type: listener}` map and returns a single dispose function that removes all of them. Each listener's event argument is still strongly typed per event type, and the optional `options` argument is shared across every listener:\n\n```js\nimport {registerEventListeners} from 'lexical';\n\nconst removeListeners = registerEventListeners(\n rootElement,\n {\n click: onClick,\n keydown: onKeyDown, // receives a KeyboardEvent\n },\n {capture: true}, // shared by both listeners\n);\n```\n\nBecause `options` is shared, register a group that needs different options (such as a different `capture` flag) with a separate `registerEventListeners` call and combine the results with `mergeRegister`.\n\n## 2. Directly Attach Handlers\n\nIn some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that your handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](listeners.md).\n\n```js\nconst registeredElements: WeakSet = new WeakSet();\nconst removeMutationListener = editor.registerMutationListener(nodeType, (mutations) => {\n editor.getEditorState().read(() => {\n for (const [key, mutation] of mutations) {\n const element: null | HTMLElement = editor.getElementByKey(key);\n if (\n // Updated might be a move, so that might mean a new DOM element\n // is created. In this case, we need to add an event listener too.\n (mutation === 'created' || mutation === 'updated') &&\n element !== null &&\n !registeredElements.has(element)\n ) {\n registeredElements.add(element);\n element.addEventListener('click', (event: Event) => {\n alert('Nice!');\n });\n }\n }\n });\n});\n\n// teardown the listener - return it from an extension's `register` so the\n// editor removes it when it is disposed.\nremoveMutationListener();\n```\nNotice that here we don't worry about cleaning up, as Lexical will dereference the underlying DOM nodes and allow the JavaScript runtime garbage collector to clean up their listeners.\n\n## 3. Use NodeEventPlugin\n\nIf you're using React, we've wrapped approach #2 up into a simple React plugin that you can render inside your composer to achieve the same effect, without worrying about the details:\n\n```jsx\n\n {\n alert('Nice!');\n }}\n />\n\n```\n\nIf the editor lives inside a shadow root or an iframe, see\n[Shadow DOM and iframes](./shadow-dom.md) for the helper to read\n`event.target` through the shadow boundary — the browser retargets it to the\nshadow host on listeners attached above the boundary, so a plain\n`event.target` won't match a node inside the editor.\n","packages/lexical-website/docs/concepts/editor-state.md":"\n\n# Editor State\n\n## Why is it necessary?\n\nWith Lexical, the source of truth is not the DOM, but rather an underlying state model\nthat Lexical maintains and associates with an editor instance.\n\nWhile HTML is great for storing rich text content it's often \"way too flexible\" when it comes to text editing.\nFor example the following lines of content will produce equal outcome:\n\n```html\nLexical\nLexical\nLexical\n```\n\n
\n See rendered version!\n
\n Lexical\n Lexical\n Lexical\n
\n
\n\nOf course, there are ways to normalize all these variants to a single canonical form, however this would require DOM manipulation and so re-rendering of the content. And to overcome this we can use Virtual DOM, or State.\n\nOn top of that it allows to decouple content structure from content formatting. Let's look at this example stored in HTML:\n\n```html\n

Why did the JavaScript developer go to the bar? Because he couldn't handle his Promises

\n```\n\n
\n \"Nested\n
Nested structure of the HTML state because of the formatting
\n
\n\nIn contrast, Lexical decouples structure from formatting by offsetting this information to attributes. This allows us to have canonical document structure regardless of the order in which different styles were applied.\n\nHere is the same content as a Lexical node tree, printed the way the\n[tree view](/docs/getting-started/devtools) shows it (the numbers are node keys):\n\n```text\nroot\n └ (2) paragraph\n ├ (3) text \"Why did the JavaScript developer go to the bar? \"\n ├ (4) text \"Because he couldn't handle his \" { format: bold }\n ├ (5) text \"Promise\" { format: bold, italic }\n └ (6) text \"s\" { format: bold }\n```\n\nThe paragraph's children are a flat list of text nodes, and the formatting is a\nproperty of each one, so there is only one way to represent this content.\n\n## Understanding the Editor State\n\nYou can get the latest editor state from an editor by calling `editor.getEditorState()`.\n\nEditor states have two phases:\n\n- During an update they can be thought of as \"mutable\". See \"Updating state\" below to\n mutate an editor state.\n- After an update, the editor state is then locked and deemed immutable from there on. This\n editor state can therefore be thought of as a \"snapshot\".\n\nEditor states contain two core things:\n\n- The editor node tree (starting from the root node). See\n [Document Model](./document-model.md) for how the tree is shaped.\n- The editor [selection](./selection.md) (which can be null).\n\nFor example, \"Hello world\" with a link around \"world\" and the caret at the\nend looks like this:\n\n```mermaid\nflowchart TB\n accTitle: A simple editor state\n accDescr: The root contains a paragraph with a \"Hello \" text node and a link. The link contains the \"world\" text node. The selection's anchor and focus both point to offset 5 in \"world\".\n subgraph state[\"EditorState\"]\n direction TB\n root[\"Root\"] --> paragraph[\"Paragraph\"]\n paragraph --> hello[\"Text: 'Hello '\"]\n paragraph --> link[\"Link\"]\n link --> world[\"Text: 'world'\"]\n selection[\"Selection\"] -.->|\"caret at offset 5\"| world\n end\n```\n\n`editor.getEditorState()` returns the latest committed state. Its `toJSON()`\nmethod serializes the document tree only; the selection and the runtime node\nkeys are not included. To restore saved content, pass the JSON to\n`editor.parseEditorState()` and the result to `editor.setEditorState()`. The\neditor must have the same node types registered. See\n[Serialization](../serialization/serialization.md) for JSON, HTML, and\nMarkdown.\n\nHere's an example of how you can initialize an editor with saved content and\nthen persist it. The saved JSON is passed as the editor's `$initialEditorState`:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\n// Get the saved content (e.g. loaded from a backend)\nconst initialEditorState = await loadContent();\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n);\neditor.setRootElement(document.getElementById('editor'));\n\n// Store the content (e.g. when the user submits a form)\nasync function onSubmit() {\n await saveContent(JSON.stringify(editor.getEditorState()));\n}\n```\n\nWith React, pass the extension to `LexicalExtensionComposer`. A component\nrendered inside it can reach the editor with `useLexicalComposerContext()`:\n\n```jsx\nimport {LexicalExtensionComposer} from '@lexical/react/LexicalExtensionComposer';\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\nimport {useMemo} from 'react';\n\nfunction SaveButton() {\n const [editor] = useLexicalComposerContext();\n return (\n saveContent(JSON.stringify(editor.getEditorState()))}>\n Save\n \n );\n}\n\nfunction Editor({initialEditorState}) {\n // The editor is recreated whenever this extension changes,\n // so keep it stable for the life of the editor.\n const extension = useMemo(\n () =>\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n [initialEditorState],\n );\n return (\n \n \n \n );\n}\n```\n\n`$initialEditorState` is applied once, when the editor is built; changing it\nlater has no effect on that editor. See \"Updating state\" below for the proper\nway to change editor state after initialization.\n\n`$initialEditorState` accepts:\n\n- a JSON string or a parsed `SerializedEditorState` object, passed to\n `editor.parseEditorState()` (as in the example above);\n- an `EditorState` instance, applied directly with `editor.setEditorState()`;\n- a function `(editor) => void`, run inside `editor.update(...)`;\n- `null`, which skips default initialization entirely. Use this with\n [collaboration](/docs/collaboration/react) so that the Yjs document, not\n Lexical, owns the initial state.\n\nOmitting the field (or passing `undefined`) seeds the root with a default empty\n`ParagraphNode`. The two are not interchangeable: `null` leaves the root with no children,\nwhile `undefined` produces a single empty line. If your `loadContent` may yield `null` or\n`undefined` for new documents, coalesce to `undefined` (e.g. `(await loadContent()) ?? undefined`)\nso the editor still gets the default paragraph rather than the collab-style uninitialized\nstate.\n\nThe legacy `LexicalComposer` takes the same values as `initialConfig.editorState`,\nexcept that a function there only runs if the root is still empty.\n\n## Updating state\n\nAll reads and writes of the document happen inside a synchronous callback:\n\n```js\nimport {$createParagraphNode, $createTextNode, $getRoot} from 'lexical';\n\neditor.update(() => {\n const paragraph = $createParagraphNode();\n paragraph.append($createTextNode('Hello world'));\n $getRoot().append(paragraph);\n});\n\nconst text = editor.read('force-commit', () => $getRoot().getTextContent());\n```\n\n### The `$` function convention {#dollar-functions}\n\nFunctions whose names start with `$`, such as `$getRoot()` and\n`$getSelection()`, only work inside one of these callbacks, because they act\non the active editor state. Calling them anywhere else throws an error. The\nconvention is similar to React Hooks:\n\n| | React Hooks | Lexical `$` functions |\n| -- | -- | -- |\n| Naming | `useFunction` | `$function` |\n| Can only be called | while rendering a component | inside an update or read |\n| Can call others of the same kind | ✅ | ✅ |\n| Must be synchronous | ✅ | ✅ |\n| Must be called unconditionally, in the same order | ✅ | ❌ No such rule |\n\nCommand handlers and node transforms already run inside an update, so they\ncan call `$` functions directly.\n\nThis works because, while a callback runs, Lexical keeps the active editor and\nthe active editor state in module-level variables, and `$` functions read\nthem: `$getRoot()` returns the root of the active state, and `$getEditor()`\nreturns the active editor. Because the callback is synchronous, nothing else\ncan run in between and change them. The same mechanism enforces the\ndifference between reads and updates. Inside a read, a method that would\nchange a node throws `Cannot use method in read-only mode.`\n\nGive your own functions a `$` prefix when they call `$` functions, so it is\nclear where they can be used. The\n[`@lexical/rules-of-lexical`](/docs/packages/lexical-eslint-plugin) ESLint rule\nchecks this convention.\n\nThe same rule applies to node objects. Call node methods only inside a read or\nupdate. Every node has a key that identifies it across versions of the editor\nstate, and node methods use that key to find the latest version of the node.\nThis is why a node reference taken earlier in an update stays usable after the\nnode changes. Keys exist only at runtime: they are not serialized, and you\nshould treat them as opaque.\n\nBecause the callbacks are synchronous, do any asynchronous work (fetching\ndata, awaiting a promise) first, and then enter an update with the result.\n\nAvoid nesting one `editor.update()` inside another: the inner update does not\nrun immediately but is queued to run after the outer one. Never start an\nupdate inside a read.\n\nEach update works on a pending copy of the editor state, and updates made in\nthe same tick are committed and reconciled to the DOM together. See\n[Updates](./updates.mdx#update-lifecycle) for the full lifecycle.\n\n### Replacing the state\n\nAnother way to set state is `setEditorState` method, which replaces current state with the one passed as an argument.\n\nHere's an example of how you can set editor state from a stringified JSON:\n\n```js\nconst editorState = editor.parseEditorState(editorStateJSONString);\neditor.setEditorState(editorState);\n```\n\n:::warning\n\n`setEditorState` rejects an `EditorState` that satisfies `editorState.isEmpty()` — i.e.\nthe root is the only node and there is no selection. In a development build it throws\n`\"setEditorState: the editor state is empty. Ensure the editor state's root node never\nbecomes empty.\"`; in production it warns with the same message and recovers by appending\nan empty `ParagraphNode`, so the editor stays usable. The `EditorState` produced by\ninitializing with `editorState: null` and never appending content (typical for a\ncollaboration document before peers connect) has exactly this shape, so persisting and\nreloading such a state hits this path. Note that `parseEditorState` itself succeeds — the\ncheck lands on the apply step. To avoid relying on the recovery, guard with\n`editorState.isEmpty()` before calling `setEditorState`, or seed the document with a\n`ParagraphNode` before serializing.\n\n:::\n\n## Reading state\n\nWhich state you see depends on how you read it:\n\n- Inside `editor.update()` you see the **pending** state, where your changes\n are visible but transforms and reconciliation may not have run yet.\n `editor.read('pending', fn)` gives you the same view without allowing\n changes.\n- `editor.read('force-commit', fn)` first commits any pending updates, so it\n always sees a consistent, reconciled state. Do not call it inside an update.\n `editor.read(fn)` with no mode does the same thing, and is kept for\n convenience and backwards compatibility. Inside a mutation or update\n listener it does not commit an update that another listener started (that\n update commits after the listeners have run, so they observe commits in\n order); use `editor.read('latest', fn)` there.\n- `editor.read('latest', fn)` reads the most recently reconciled state without\n committing anything, so pending changes are not visible.\n- `editorState.read(fn, {editor})` reads one particular snapshot, such as the\n `editorState` an update listener receives. Passing the `editor` keeps\n `$getEditor()` and extension lookups working inside the callback.\n\n## State update listener\n\nIf you want to know when the editor updates so you can react to the changes, you can add an update\nlistener to the editor, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(\n () => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n },\n // Passing the editor keeps $getEditor() and extension lookups working.\n {editor},\n );\n});\n```\n\n## When are Listeners, Transforms, and Commands called?\n\nThere are several types of callbacks that can be registered with the editor that are related to\nupdates of the Editor State.\n\n| Callback Type | When It's Called |\n| -- | -- |\n| Update Listener | After reconciliation |\n| Mutation Listener | After reconciliation |\n| Node Transform | During `editor.update()`, after the callback finishes, if any instances of the node type they are registered for were updated |\n| Command | As soon as the command is dispatched to the editor (called from an implicit `editor.update()`) |\n\n## Synchronous reconciliation with discrete updates\n\nWhile commit scheduling and batching are normally what we want, they can sometimes get in the way.\n\nConsider this example: you're trying to manipulate an editor state in a server context and then persist it in a database.\n\n```js\neditor.update(() => {\n // manipulate the state...\n});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\nThis code will not work as expected, because the `saveToDatabase` call will happen before the state has been committed.\nThe state that will be saved will be the same one that existed before the update.\n\nFortunately, the `discrete` option for `LexicalEditor.update` forces an update to be immediately committed.\n\n```js\neditor.update(() => {\n // manipulate the state...\n}, {discrete: true});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\n### Cloning state\n\nLexical state can be cloned, optionally with custom selection. One of the scenarios where you'd want to do it\nis setting editor's state but not forcing any selection:\n\n```js\n// Passing `null` as a selection value to prevent focusing the editor\neditor.setEditorState(editorState.clone(null));\n```\n","packages/lexical-website/docs/concepts/headless.md":"# Running Without a Browser\n\nThe DOM is only needed to show an editor on screen. Because every read and\nupdate goes through the editor state, Lexical also works where there is no\nbrowser DOM:\n\n- **With no DOM at all.** An editor that has no root element skips\n reconciliation and DOM selection entirely, so you can build one with\n `buildEditorFromExtensions()` and never call `setRootElement()`. Adding\n `HeadlessExtension` from `@lexical/headless` makes that explicit: attaching a\n root element then throws, and nested editors are headless too. Updates,\n transforms, listeners, commands, and JSON serialization all still work,\n which is enough to process documents on a server, apply changes from a\n collaboration backend, or write tests.\n- **With a virtual DOM** such as happy-dom or jsdom, for the features that\n create DOM nodes, like HTML import and export. `withDOM()` from\n `@lexical/headless/dom` runs a callback with a temporary happy-dom window,\n for example to convert HTML on a server.\n\n## Example: converting saved JSON to HTML on a server\n\n```ts\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {HeadlessExtension} from '@lexical/headless';\nimport {withDOM} from '@lexical/headless/dom';\nimport {$generateHtmlFromNodes} from '@lexical/html';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [HeadlessExtension, RichTextExtension],\n name: '@my-app/server-editor',\n }),\n);\n\nexport function jsonToHtml(json: string): string {\n editor.setEditorState(editor.parseEditorState(json));\n return withDOM(() => editor.read(() => $generateHtmlFromNodes(editor)));\n}\n```\n\nThe editor must have the same node types registered as the editor that saved\nthe JSON, which is why it uses the same extensions. JSON and Markdown\nconversion do not need `withDOM()`.\n\n## `createHeadlessEditor()`\n\nBefore extensions, headless editors were created with `createHeadlessEditor()`\nfrom `@lexical/headless`. It still works, and it makes DOM-only methods such as\n`registerRootListener` and `registerMutationListener` throw. Because many\nextensions register those listeners, use `HeadlessExtension` with\n`buildEditorFromExtensions()` in new code.\n","packages/lexical-website/docs/concepts/history.md":"# History\n\nLexical adds support for Undo and Redo through the `@lexical/history` package —\n`registerHistory`, the `HistoryExtension` extension, or the `HistoryPlugin`\nReact component from `@lexical/react/LexicalHistoryPlugin`. Part of undo and redo requires supporting coalescing of certain dynamic operations such as continuous typing. The below provides background information regarding the continuous typing undo coalescing feature.\n\n**Undo Coalescing of Typed Text**\n\n**TL;DR**\nWhen working with text editors, users expect a well polished undo experience. A key part of this is a smooth, well thought out workflow when undoing continuous typing events. For this post, strict typing events may be limited to typing characters, backspacing and forward deleting. Users generally expect that continuous typing should fully undo with a single undo gesture and that they don’t require separate undo gestures for each character.\nThe algorithm that covers this is “undo coalescing of typed text” and there’s a certain degree of nuance involved. This post covers that nuance while attempting to avoid prescriptive implementation details.\n\n**What Kind of Edits Require Coalescing?**\nAs mentioned above, continuous typing should be coalesced into a single undo action. Continuous typing is a loaded phrase and we’ll get into some details below.\nThere are other types of edits that require undo coalescing such as rapidly resizing an image or rapidly changing the font size of selected text. These latter two examples fall under what might be termed “dynamic operations” and their implementation might vary quite a bit from coalescing of typing.\n\n**What Constitutes Continuous Typing?**\nFor the purposes of undo coalescing, continuous typing events are safely limited to these three actions:\n\n1. Forward typing characters (heads up, composed character typing discussed later).\n2. Deleting backwards, e.g. backspace gestures including backspace key presses.\n3. Forward deletion, e.g. forward delete gestures including Delete key presses.\n\nAny interruption to the above breaks the notion of continuous typing. Note that switching between either of these three actions may itself be considered an interruption of continuous typing or it may not. This ends up being a usability decision. In my opinion, when examining various word processors, switching between these three actions should maintain continuity, because users often make typos or corrections in the flow of typing and therefore would lean towards the whole sequence of typing, backspacing and deleting to be within a single undoable session.\nNote that Google Docs and Quip treat a switch between typing, backspacing and deleting as disruptions to the continuous typing sessions.\n\n**Start with Selected Text and Followup with Typing**\nLet’s start with some selected text. The user may have selected the text directly, as a result of pasting text or through some other sequence of steps. When followed by continuous typing, the initial selection should be included along with the following typing events as part of a single coalesced undo session.\n\n**Timeouts**\nText editing is generally a modeless user experience and so just about any event beyond the above typing actions will disrupt continuous typing. The first and foremost is a timeout.\nQuip seems to require continuous typing to occur within 1 second intervals, whereas Google Docs requires about 2 seconds. In my opinion, the timeout may stretch to as long as 3 to 5 seconds. The more time between typing events, the more chance the user has to intentionally input a block of text, a thought or concept.\nThe use of a timeout is not necessarily required, and the amount of time is certainly up for debate. Collaborative co-editing also makes use of timeouts when grouping text that is merged across clients. Longer timeouts tend to make collaboration a smoother, less disruptive experience, because receiving other client input while expressing one’s thoughts tends to be unhelpful.\nImplementers should consider the correct timeout based on their customer expectations and related collaborative features that might share this timeout.\n\n**Hard and Soft Returns**\nHard returns as generated by pressing the Return key tend to disrupt and thereby reset continuous typing.\nFor Google Docs and Quip, soft returns as generated by pressing shift+Return key do not terminate continuous typing. This makes sense in that the soft return ends text wrap but does not end the paragraph.\n\n**Changing Selections and Key Focus**\nAny change to the selection by the user should terminate coalescing. This includes:\n\n- Arrow gesture navigation.\n- Gestures to select a word, a sentence or a paragraph.\n- Any other selection change that does not move the blinking caret to the next or previous character by way of the above mentioned typing events.\n\nAdditionally, ending keyboard focus on the editing window, including moving focus to another editing window or a different view within the same window should also terminate coalescing. This also includes setting focus to modal popovers, such as, for example, a hyperlink property editor.\n\n**Composed Characters**\nCharacter composition occurs when typing diacritics, CJK and even emojis. The process usually involves at least these three phases:\n\n- Start composition.\n- Replace composed text with other text and remain composing. This step may occur many times within a single composition session.\n- Stop composition either through accepting the text or canceling the latest input.\n\nCoalescing should terminate at start composition. Replacing composed text should generally be coalesced. Stopping composition may or may not reset coalescing depending upon the implementation. Quip appears to try to coalesce multiple composed characters, but disrupts coalescing when switching between composed and non-composed characters. Google Docs appears to disrupt coalescing more frequently. Both coalesce the text replacements.\n\n**Auto Correct, Spelling Corrections and Text Substitutions**\nText substitution behaves much like composed characters. When the text is transformed, the coalescing should terminate and the transformed text becomes the first coalesced entry in the next undo session.\n\n**Copy & Pasting**\nAny actions like copy and paste typically trigger events that are not part of the 3 continuous typing actions described above. So, copy and paste also terminates coalescing.\n\n**In Conclusion**\nText undo coalescing greatly improves the usability of undo in that it allows the user to bypass all the intermediate events that went into forming or re-forming text within a paragraph. Given the modeless nature of text editing, limiting continuous typing to strictly three events allows for a robust and clean implementation. Implementers will need tight bottlenecks to trap selection changes, key focus changes as well as changes from collaborative clients. While the above is not complete by any means, I hope readers will find it helpful.\n\n## Tuning HistoryExtension for memory and long sessions\n\n`HistoryExtension` ships with config values chosen for the common case\nof a short-lived editor on a richly interactive surface. For\napplications that keep an editor mounted for a long time — chat\nthreads, long documents, anything where the user may produce thousands\nof distinct history events without reloading the page — two settings\nare worth tuning explicitly.\n\n### `maxDepth` — cap the undo stack\n\nBy default `maxDepth` is `null`, meaning the undo stack is\n**unbounded**. Every separate-history boundary (see \"What Constitutes\nContinuous Typing?\" above) pushes a `HistoryStateEntry` that retains a\nfull `EditorState` snapshot. Snapshots share a copy-on-write\n`NodeMap`, so the marginal cost of any one entry is small, but it is\nnot zero — and an unbounded stack accumulates a long tail over time.\n\nSet a finite `maxDepth` to keep the stack at a fixed length. The\nextension FIFO-evicts the oldest entries past the cap; older snapshots\nbecome unreachable and can be collected.\n\n```ts\nimport {configExtension, defineExtension} from 'lexical';\nimport {HistoryExtension} from '@lexical/history';\n\nconst editorExtension = defineExtension({\n // ...\n dependencies: [\n // 100 events is a reasonable starting point that supports a deep\n // enough undo stack for almost any interactive editing session.\n configExtension(HistoryExtension, {maxDepth: 100}),\n ],\n});\n```\n\nThe cap is also exposed as a writable signal on\n`HistoryExtension.output.maxDepth`, so it can be reconfigured at\nruntime (the new value applies to future pushes — the current stack\nis not retroactively trimmed when the cap is lowered).\n\n### `delay` — coalesce more aggressively\n\n`delay` is the merge window during which adjacent edits collapse into\nthe current history entry instead of pushing a new one. The default is\n`300`ms. A longer delay means fewer history events for the same\ntyping burst, which:\n\n- reduces the rate at which `undoStack` grows, multiplying the effect\n of any `maxDepth` cap, and\n- gives the user undo gestures that match larger semantic chunks of\n their writing.\n\nFor text-heavy editors a value in the `500`–`1000`ms range is common.\n\n```ts\nconfigExtension(HistoryExtension, {delay: 500, maxDepth: 100}),\n```\n\n### When NOT to cap history\n\nIf your editor is short-lived (mounted only for the duration of a\nmodal, page form, or single message draft) and undo is expected to\nreach back to the document's initial state, the default `maxDepth:\nnull` is fine — the stack will be discarded with the editor instance.\nThe cap matters when an editor is **long-lived** and can accumulate\nthousands of distinct history events without unmounting.\n","packages/lexical-website/docs/concepts/key-management.md":"# Key Management\n\nKeys are a fundamental concept in Lexical that enable efficient state management and node tracking. Understanding how keys work is crucial for building reliable editor implementations.\n\n## What are Keys?\n\nThe `__key` property is a unique identifier assigned to each node in the Lexical editor. These keys are:\n- Automatically generated by Lexical\n- Used to track nodes in the editor state\n- Essential for state management and updates\n- Immutable during a node's lifecycle\n\n## When to Use `__key`?\n\n### ✅ Correct Usage\n\nKeys should ONLY be used in two specific situations:\n\n1. **In Node Constructors**\n```typescript\nclass MyCustomNode extends ElementNode {\n constructor(someData: string, key?: NodeKey) {\n super(key); // Correctly passing key to parent constructor\n this.__someData = someData;\n }\n}\n```\n\n2. **In Static Clone Methods**\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### ❌ Incorrect Usage\n\nNever use keys in these situations:\n\n```typescript\n// ❌ Don't pass keys between different nodes\nconst newNode = new MyCustomNode(existingNode.__key);\n\n// ❌ Don't manipulate keys directly\nnode.__key = 'custom-key';\n```\n\n## How Lexical Uses Keys\n\n### Diagram\n\nThe dotted outlines show nodes that are re-used in a zero-copy fashion from one EditorState to the next\n\n```mermaid\ngraph TB\n subgraph s0[\"Initial State\"]\n direction TB\n m0[\"NodeMap (v0)\"]\n m0 -->|Key A| n0a[\"A (v0)\"]\n m0 -->|Key B| n0b[\"B (v0)\"]\n end\n subgraph s1[\"Create Node C\"]\n direction TB\n style n1a stroke-dasharray: 5 5\n style n1b stroke-dasharray: 5 5\n m1[\"NodeMap (v1)\"]\n m1 -->|Key A| n1a[\"A (v0)\"]\n m1 -->|Key B| n1b[\"B (v0)\"]\n m1 -->|Key C| n1c[\"C (v0)\"]\n end\n subgraph s2[\"Update Node A\"]\n direction TB\n style n2a stroke-dasharray: 5 0\n style n2b stroke-dasharray: 5 5\n style n2c stroke-dasharray: 5 5\n m2[\"NodeMap (v1)\"]\n m2 -->|Key A| n2a[\"A (v1)\"]\n m2 -->|Key B| n2b[\"B (v0)\"]\n m2 -->|Key C| n2c[\"C (v0)\"]\n end\n s0 -.-> s1 -.-> s2\n```\n\n### Node Map Structure\n\nThe EditorState maintains a `Map` that tracks all nodes. Nodes refer to each other using keys in their internal pointers:\n\n```typescript\n// Internal node structure (not for direct usage)\n{\n __prev: null | NodeKey,\n __next: null | NodeKey,\n __parent: null | NodeKey,\n // __first, __last and __size are only for ElementNode to track its children\n __first: null | NodeKey,\n __last: null | NodeKey,\n __size: number\n}\n```\n\nThese internal pointers maintain the tree structure and should never be manipulated directly.\n\n### Key-Related APIs\n\n1. **Editor Methods**\n ```typescript\n // Get node by key\n const node = $getNodeByKey(key);\n\n // Get the DOM element a node key is reconciled to\n const element = editor.getElementByKey(key);\n\n // Get latest version of a node\n const latest = node.getLatest();\n \n // Get mutable version for updates\n const mutable = node.getWritable();\n ```\n\n### Key Lifecycle\n\nNodeKeys are ephemeral and have several important characteristics:\n\n1. **Serialization**\n - Keys are never serialized\n - New keys are generated when deserializing (from JSON/HTML)\n - Keys are only meaningful within their EditorState instance\n\n2. **Uniqueness**\n - Keys are unique within an EditorState\n - Current implementation uses serial numbers for debugging\n - Should be treated as random and opaque values\n - Never logically reused\n\nKeys are used internally by Lexical to:\n1. Track nodes in the editor state\n2. Manage node updates and versions\n3. Maintain referential integrity\n4. Enable efficient state updates\n\n## Common Pitfalls\n\n1. **Key Reuse**\n ```typescript\n // ❌ Never do this\n function duplicateNode(node: LexicalNode) {\n return new SameNodeType(data, node.__key);\n }\n ```\n\n2. **Manual Key Assignment**\n ```typescript\n // ❌ Never do this\n node.__key = generateCustomKey();\n ```\n\n3. **Incorrect Constructor/Clone Implementation**\n ```typescript\n // ❌ Never do this - missing key in constructor\n class MyCustomNode extends ElementNode {\n constructor(someData: string) {\n super(); // Missing key parameter\n this.__someData = someData;\n }\n }\n\n // ✅ Correct implementation\n class MyCustomNode extends ElementNode {\n __someData: string;\n\n constructor(someData: string, key?: NodeKey) {\n super(key);\n this.__someData = someData;\n }\n \n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__someData = prevNode.__someData;\n }\n }\n ```\n\n4. **Node Replacement**\n ```typescript\n // ❌ Never re-use the key when changing the node class\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(node.__key),\n withKlass: CustomNodeType\n }\n ]\n };\n\n // ✅ Correct: Use node replacement configuration\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(),\n withKlass: CustomNodeType\n }\n ]\n };\n ```\n\n For proper node replacement, see the [Node Replacement guide](node-replacement.md).\n\n## Best Practices\n\n1. **Let Lexical Handle Keys**\n ```typescript\n import {$applyNodeReplacement} from 'lexical';\n\n // Create node helper function\n export function $createMyCustomNode(data: string): MyCustomNode {\n return $applyNodeReplacement(new MyCustomNode(data));\n }\n ```\n\n## Testing Considerations\n\nWhen writing tests involving node keys:\n\n```typescript\ntest('node creation', async () => {\n await editor.update(() => {\n // ✅ Correct: Create nodes normally\n const node = new MyCustomNode(\"test\");\n \n // ✅ Correct: Keys are automatically handled\n expect(node.__key).toBeDefined();\n expect(node.__key).not.toBe('');\n });\n});\n```\n\n## Performance Impact\n\nUnderstanding key management is crucial for performance:\n\n1. Keys enable efficient node lookup (O(1))\n2. Proper key usage prevents unnecessary re-renders\n3. Lexical's key system optimizes state updates\n4. Improper key manipulation can cause performance issues\n\n## Common Questions\n\n**Q: How do I reference a node later?**\nA: Store a reference to the node. Conventionally, all node methods will use `getLatest()` or `getWritable()` which will look up the latest version of that node before reading or writing its properties, which is equivalent to using the key but is type-safe (but may cause errors if you try to use a reference to a node that no longer exists). In some situations it may be preferable to use the key directly, which is also fine.\n\n**Q: How do I ensure unique nodes?**\nA: Let Lexical handle key generation and management. Focus on node content and structure. ","packages/lexical-website/docs/concepts/keyboard-accessibility.md":"# Keyboard Accessibility\n\nLexical follows the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) keyboard model. This page documents the contracts that plugin authors and host applications rely on, so a Lexical editor can sit inside a larger keyboard-accessible flow without trapping or surprising the user.\n\n## Tab key\n\nBy default, `Tab` inside the editor follows the browser's normal focus order — it moves to the next focusable element on the page. There is no keyboard trap.\n\nThe optional `TabIndentationExtension` (`@lexical/extension`) takes over `Tab` and uses it for block indent / outdent. Hosts that mount this extension opt in to that behavior. WCAG 2.1.2 (No Keyboard Trap) still applies — pressing `Escape` blurs the editor (see below), at which point `Tab` leaves the editor again.\n\n## Escape key\n\nPressing `Escape` while the editor has focus calls `editor.blur()` via the rich-text Escape command handler (registered at `COMMAND_PRIORITY_EDITOR`). The handler only blurs when the current selection is a range selection; with a `NodeSelection` (or no selection) it returns `false` and falls through without blurring. After blur, the next `Tab` advances to the page's next focusable element — so the editor is not a hard keyboard trap. (`TabIndentationExtension` consumes `Tab` only while a range selection is active, and its own source notes that taking over `Tab` is generally discouraged for keyboard accessibility, so treat WCAG 2.1.2 conformance as something to verify in your integration rather than a guarantee.)\n\nPlugin authors who want to intercept `Escape` (modal close, dropdown close, etc.) should register their handler at a higher priority and return `true` to stop the command chain. Common patterns already established in the codebase:\n\n| Priority | Caller | Purpose |\n| --- | --- | --- |\n| `HIGH` | Floating link editor | Close the floating UI, keep editor focus |\n| `HIGH` | Equation component (while editing) | Close the equation editor input |\n| `NORMAL` | Comment plugin | Cancel inline comment editing |\n| `LOW` | Image component | Escape out of caption / resize editing: drop the inner selection and restore the `NodeSelection` on the image decorator |\n| `EDITOR` | Rich text (default) | `editor.blur()` (range selection only) |\n\nHandlers that return `false` let the chain continue, so Escape can still fall through to the default blur even after a higher-priority handler runs.\n\nSome host UI binds its close handler directly to a DOM `keydown` listener rather than going through `KEY_ESCAPE_COMMAND` — the playground's `Modal` via `window.addEventListener('keydown', ...)` and its `DropDown` via a React `onKeyDown` on the menu. Those paths run alongside the table above; they do not participate in the editor's command priority chain.\n\n## React hooks and `@lexical/a11y` extensions\n\nThe keyboard helpers below ship as `@lexical/a11y` _extensions_ — the extension is the API and does all of the work (event listeners, focus management, the live region). The `@lexical/react` hooks (`useLexicalFocusManagerRef`, `useLexicalRovingTabIndexRef`, `useLexicalFocusTrapRef`, `useLexicalAriaLiveRegion`) are thin React adapters that only _communicate_ with their extension: each returns a `RefCallback` (or an `announce` function) that drives the extension's signals. Using a hook therefore **requires** its matching extension to be registered in the editor's extension tree — it is not an optional integration path. Non-React hosts (Svelte, Vue, vanilla DOM) use the extensions directly and skip the hooks.\n\n## Toolbar focus jump\n\nThe playground uses `useLexicalFocusManagerRef` (`@lexical/react/useLexicalFocusManagerRef`) to provide a documented shortcut for moving focus from the editor to the toolbar without tabbing through the page. The hook returns a `RefCallback` that registers the attached element as a focus-managed toolbar. It listens for `Alt+F10` inside the editor and moves focus into the toolbar — preferring the item that currently carries `tabindex=\"0\"` (the active roving item, when paired with `useLexicalRovingTabIndexRef`), and otherwise the first focusable item. While focus is in the toolbar, pressing `Escape` restores both focus and the editor's prior selection via `editor.focus()`. Multiple toolbars can be registered simultaneously. Requires `FocusManagerExtension` from `@lexical/a11y` in the editor's extension tree.\n\nThis matches the WAI-ARIA editor menubar pattern and the convention used by Word and CKEditor. Hosts that don't mount `useLexicalFocusManagerRef` get the default browser flow (Tab in, Tab out).\n\n## Toolbar arrow-key navigation\n\nToolbars that opt into `useLexicalRovingTabIndexRef` (`@lexical/react/useLexicalRovingTabIndexRef`) collapse to a single tab stop: arrow keys move between items inside the toolbar; `Tab` moves past the toolbar as a whole. Items keep `tabindex=\"-1\"` except the active one (`tabindex=\"0\"`). The hook returns a `RefCallback` — multiple containers can be registered simultaneously. Tracks the WAI-ARIA toolbar pattern. Requires `RovingTabIndexExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Modal focus trap\n\n`useLexicalFocusTrapRef` (`@lexical/react/useLexicalFocusTrapRef`) returns a `RefCallback` that cycles `Tab` / `Shift+Tab` inside a modal container and restores focus to the previously-focused element on deactivation. While active, the trap also installs a document-level `focusin` listener that pulls any focus landing outside the container back to the first focusable descendant (or the container itself) — so it recovers from the browser routing `Tab` out to its own chrome. Although several containers can be _registered_, only one trap should be _active_ at a time: concurrent traps install competing `focusin` listeners and fight over focus. Escape is **not** intercepted by the hook — modal owners handle the close key themselves, so the editor's Escape contract above stays predictable. Requires `FocusTrapExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Screen reader announcements\n\n`useLexicalAriaLiveRegion` (`@lexical/react/useLexicalAriaLiveRegion`) returns a stable `announce(message)` function. The hook itself mounts no DOM — like the others above, it is a thin adapter that **requires `AriaLiveRegionExtension` from `@lexical/a11y` in the editor's extension tree**. That extension owns the lifecycle of the visually-hidden region (`role=\"status\"`, `aria-atomic`, `aria-live` defaulting to `polite` — configurable via its `politeness` config): the region is created in the extension's `register` step and disposed on the editor's teardown, not on the hook's unmount. `EditorModeAnnounceExtension` (mode transitions via `registerEditableListener`) and `HistoryAnnounceExtension` (undo / redo via `UNDO_COMMAND` / `REDO_COMMAND`) announce through the same region. Both extensions accept optional message overrides for i18n.\n\n## Component ARIA quick reference\n\nWhere Lexical already applies ARIA attributes today (set in each component's `createDOM` / `updateDOM`, declaratively in the surrounding React tree, or applied imperatively via `setAttribute` on a managed or portaled element — as the typeahead menu and the live region do):\n\n| Component | role | aria-\\* attributes |\n| --- | --- | --- |\n| `ToolbarPlugin` (playground) | `toolbar` | `aria-label` |\n| `Modal` (playground) | `dialog` | `aria-modal`, `aria-labelledby` |\n| `LexicalListItemNode` (check list leaf) | `checkbox` | `aria-checked` |\n| `LexicalMenu` typeahead popup | `listbox` | `aria-label` |\n| Editor root (while typeahead is open) | — | `aria-controls`, `aria-activedescendant` |\n| `EquationNode` (playground) | `math` | `aria-label` |\n| `useLexicalAriaLiveRegion` region | `status` | `aria-live`, `aria-atomic` |\n\nCustom nodes follow the same pattern: set the attributes in `createDOM` and re-apply in `updateDOM` when the state they reflect changes. There is no central ARIA contract on `LexicalNode`; treat each subclass's `createDOM` as the source of truth.\n\n## Browser notes\n\nLexical relies on the standard DOM `Escape` contract — verified on Chrome and Safari (macOS, normal window). Safari in fullscreen intercepts `Escape` at the browser level to exit fullscreen; that is the browser's contract, not Lexical's.\n\n## What this page does not cover\n\n- Touch / mobile screen reader gestures. The hooks above share the same DOM contracts with mobile (TalkBack, VoiceOver iOS) but mobile has not been exercised in this set of changes.\n- High contrast / forced-colors theming. See the playground's `index.css` `@media (forced-colors: active)` block for a baseline.\n","packages/lexical-website/docs/concepts/listeners.md":"\n\n# Listeners\n\nListeners are a mechanism that lets the Editor instance inform the user when a certain operation has occurred. All listeners follow a reactive pattern where you can do an operation upon something happening in the future. All listeners also return a function that easily allows for the\nlistener to be unregistered. Below are the different listeners that Lexical supports today:\n\n## `registerUpdateListener`\n\nGet notified when Lexical commits an update to the DOM.\n\n```js\nconst removeUpdateListener = editor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(() => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n });\n});\n\n// Do not forget to unregister the listener when no longer needed!\nremoveUpdateListener();\n```\n\nThe update listener callbacks receives a single argument containing the follow properties:\n\n- `editorState` the latest updated Editor State\n- `prevEditorState` the previous Editor State\n- `tags` a Set of all tags that were passed to the update\n- `dirtyElements` a Map of the NodeKeys of ElementNodes that were marked\n dirty, to a boolean that is true when the node was intentionally mutated\n- `dirtyLeaves` a Set of the NodeKeys of all dirty nodes that are not\n ElementNodes\n- `mutatedNodes` a Map of LexicalNode constructors to a\n `Map`, or null when no DOM was mutated. Only\n populated when at least one MutationListener is registered\n- `normalizedNodes` (advanced) the keys of TextNode descendants that were\n merged with a sibling by normalization\n\nOne thing to be aware of is \"waterfall\" updates. This is where you might schedule an update inside an update\nlistener, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // Read the editorState and maybe get some value.\n editorState.read(() => {\n // ...\n });\n\n // Then schedule another update.\n editor.update(() => {\n // ...\n });\n});\n```\n\nThe problem with this pattern is that it means we end up doing two DOM updates, when we likely could have\ndone it in a single DOM update. This can have an impact on performance, which is important in a text editor.\n\nA listener that re-enqueues work without a stop condition is worse than slow.\nThe editor keeps a cascade budget: once a run of updates re-enqueues more\nthan 100 times without yielding to the event loop, it discards the entire\npending update queue and warns. Bounded activity never reaches the limit —\nthe budget is reset from a macrotask, which a genuine runaway starves — but a\ntrue loop silently loses whatever else was queued.\n\nTo avoid this, we recommend looking into [Node Transforms](transforms.md), which allow you to listen to node changes and\ntransform them as part of the same given update, meaning no waterfalls!\n\n## `registerTextContentListener`\n\nGet notified when Lexical commits an update to the DOM and the text content of the editor changes from\nthe previous state of the editor. If the text content is the same between updates, no notifications to\nthe listeners will happen.\n\n```js\nconst removeTextContentListener = editor.registerTextContentListener(\n (textContent) => {\n // The latest text content of the editor!\n console.log(textContent);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveTextContentListener();\n```\n\n## `registerMutationListener`\n\nGet notified when a specific type of Lexical node has been mutated. There are three states of mutation:\n\n- `created`\n- `destroyed`\n- `updated`\n\nMutation listeners are great for tracking the lifecycle of specific types of node. They can be used to\nhandle external UI state and UI features relating to specific types of node.\n\nIf any existing nodes are in the DOM, and skipInitialization is not true, the listener\nwill be called immediately with an updateTag of 'registerMutationListener' where all\nnodes have the 'created' NodeMutation. This can be controlled with the skipInitialization option,\nwhich defaults to false.\n\n```js\nconst removeMutationListener = editor.registerMutationListener(\n MyCustomNode,\n (mutatedNodes, { updateTags, dirtyLeaves, prevEditorState }) => {\n // mutatedNodes is a Map where each key is the NodeKey, and the value is the state of mutation.\n for (let [nodeKey, mutation] of mutatedNodes) {\n console.log(nodeKey, mutation)\n }\n },\n {skipInitialization: false}\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveMutationListener();\n```\n\n## `registerEditableListener`\n\nGet notified when the editor's mode has changed. The editor's mode can be changed\nvia `editor.setEditable(boolean)`.\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (editable) => {\n // The editor's mode is passed in!\n console.log(editable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\n## `registerDecoratorListener`\n\nGet notified when the editor's decorator object changes. The decorator object contains\nall `DecoratorNode` keys -> their decorated value. This is primarily used with external\nUI frameworks.\n\n```js\nconst removeDecoratorListener = editor.registerDecoratorListener(\n (decorators) => {\n // The editor's decorators object is passed in!\n console.log(decorators);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveDecoratorListener();\n```\n\n## `registerRootListener`\n\nGet notified when the editor's root DOM element (the content editable Lexical attaches to) changes. This is primarily used to\nattach event listeners to the root element. *The root listener function is executed directly upon registration and then on any subsequent update.*\n\n```js\nconst removeRootListener = editor.registerRootListener(\n (rootElement, prevRootElement) => {\n //add listeners to the new root element\n //remove listeners from the old root element\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveRootListener();\n```\n","packages/lexical-website/docs/concepts/named-slots.md":"# Named Slots\n\n:::warning\n\nNamed slots are experimental. The APIs described here are tagged\n`@experimental`, may change without a major version bump, and the\nserialization and collab formats should be treated as unstable until the\nfeature is stabilized.\n\n:::\n\nNamed slots let a single host node (an ElementNode or a DecoratorNode) own\nseveral isolated editable regions addressed by name — a Card's `title`, a\nPullQuote's `quote` and `attribution` — inside the host's own EditorState.\nEach region takes its own caret and formatting, never merges across the\nboundary, and `Cmd+A` doesn't spill into the rest of the document.\n\nBefore named slots, the usual answer was a nested editor per region: every\nregion lives in its own EditorState, so moving nodes between regions and\nkeeping history and collab in sync all require serialization and extra\n`editor.update` passes. The other node shapes don't fit either: plain\nElementNode children share one undivided linked list (Backspace at a region\nstart merges it into the previous region), and a DecoratorNode is atomic, so\nLexical can't own selection, collab, or serialization inside it. With named\nslots, editing a slot is just editing the one tree.\n\n:::note\n\nNamed slots are the model-level generalization of the rendering concept\nbehind [`$getDOMSlot`](/docs/api/modules/lexical#getdomslot) /\n`ElementDOMSlot` in the\n[DOM rendering](../serialization/dom-render.md) documentation. Every\nElementNode already has one _unnamed_ children channel, and `$getDOMSlot`\ncontrols where that channel's content attaches in the node's DOM. Named\nslots are additional, explicitly-named channels alongside it — symmetric in\nthat each renders into a controllable location in the host's DOM — but they\nalso carry the model-level semantics the unnamed channel doesn't: isolation\n(the virtual shadow root below), a separate NodeKey map, and their own\nserialization and collaboration.\n\n:::\n\n## The Model\n\nA host keeps a second child channel, a `Map` of slot name to NodeKey,\nseparate from its ordinary linked-list children. A slot value has its slot\nhost pointer set and `getParent() === null`, with exactly one of the two\nnon-null: `getParent()` stops at the slot boundary, and you climb out only\nthrough [`$getSlotHost()`](/docs/api/modules/lexical#getslothost).\n\nThe slot link itself acts as a **virtual invisible shadow root** between the\nhost and the value. Isolation is structural rather than a convention — an\naccidental boundary crossing surfaces as a thrown invariant, not silent\ncorruption.\n\nIn the DOM, each value renders synchronously into a keyless\n`
\">` container parked slots-first in the host\nDOM as a **hidden placeholder** (`display: none`), in a canonical order\nderived from the host class (see [slot order](#slot-order)). Nothing is\nvisible until the host explicitly attaches the container somewhere (see\n[Rendering](#rendering)) — mirroring how\n[`getDOMSlot`](/docs/api/modules/lexical#getdomslot) gives an element\ncontrol over where its linked-list children render.\n\n## Hosts and Values\n\nAny ElementNode or DecoratorNode can host slots. An ElementNode host can mix\nslots with ordinary children (a Card with a `title` slot plus regular body\nparagraphs); a DecoratorNode host has no children channel, so slots are its\nonly editable content (a PullQuote that is otherwise atomic).\n\nA slot value is any non-inline ElementNode or DecoratorNode. The value's\nshape decides the editing model:\n\n- **A bare block** (for example a ParagraphNode) behaves as a single-line\n field with no extra wrapper in the model, the JSON, or the DOM: its virtual\n scope holds exactly one block, so Enter is a no-op (hosts may map it to\n focus movement) and a multi-block paste flattens to inline content the way\n an `` sanitizes its value — line breaks stripped, block-only\n decorators dropped.\n- **A shadow-root container** (an ElementNode whose\n [`isShadowRoot()`](/docs/api/modules/lexical#isshadowroot) returns\n `true`) behaves as a multi-block region with normal block editing inside.\n\n## Declaring and Setting Slots\n\nA host class declares its slot names in [`$config()`](nodes.mdx); values are\nattached with [`$setSlot`](/docs/api/modules/lexical#setslot):\n\n```ts\nimport {\n $create,\n $createParagraphNode,\n $setSlot,\n ElementNode,\n} from 'lexical';\n\nclass CardNode extends ElementNode {\n $config() {\n return this.config('card', {extends: ElementNode, slots: ['title']});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n}\n\nfunction $createCardNode(): CardNode {\n const card = $create(CardNode);\n // Single-line title: the bare paragraph IS the slot value. An empty\n // paragraph is an empty field; to seed default text, append a non-empty\n // TextNode (empty TextNodes are eliminated during reconciliation).\n $setSlot(card, 'title', $createParagraphNode());\n // Ordinary body child, edited like any other block.\n return card.append($createParagraphNode());\n}\n```\n\nFor a multi-block region, use a shadow-root container as the value:\n\n```ts\nclass SlotContainerNode extends ElementNode {\n $config() {\n return this.config('slot-container', {extends: ElementNode});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n isShadowRoot(): boolean {\n return true;\n }\n}\n\n$setSlot(\n pullQuote,\n 'quote',\n $create(SlotContainerNode).append(\n $createParagraphNode().append($createTextNode('First block')),\n $createParagraphNode().append($createTextNode('Second block')),\n ),\n);\n```\n\nThe core API surface (all exported from `lexical`):\n\n- [`$setSlot(host, name, node)`](/docs/api/modules/lexical#setslot) — place a value into a named slot, replacing\n any existing value under that name. Move semantics, mirroring `append`:\n the value is detached from any current parent or slot first. Throws if the\n value is inline or if the name is one of the reserved prototype keys\n (`__proto__`, `constructor`, `prototype`). Slotting a node into its own\n descendant would form a cycle; this is checked (and throws) in development\n only — in production it behaves like appending an ancestor through the\n children channel, which is likewise unguarded.\n- [`$getSlot(host, name)`](/docs/api/modules/lexical#getslot) — the value under a name, or `null`.\n- [`$getSlotNames(host)`](/docs/api/modules/lexical#getslotnames) — the host's slot names in canonical order.\n- [`$removeSlot(host, name)`](/docs/api/modules/lexical#removeslot) — detach the value under a name (the subtree is\n garbage-collected unless you reattach it elsewhere).\n- [`$getSlotHost(node)`](/docs/api/modules/lexical#getslothost) — the host a value is slotted into, or `null`.\n- [`$getSlotNameWithinHost(node)`](/docs/api/modules/lexical#getslotnamewithinhost) — the name of the slot\n a value occupies on its host (the reverse direction of `$getSlotHost`), or\n `null` when the node is not a slot value.\n- [`$getSlotFrame(node)`](/docs/api/modules/lexical#getslotframe) — the innermost slot value containing a node (the\n \"frame\" whose virtual shadow root scopes editing), or `null` when the node\n is not inside any slot.\n- [`$getSelectionSlotFrame(selection)`](/docs/api/modules/lexical#getselectionslotframe) — the slot frame a\n selection lives in, or `null` when it is outside any slot. Selection-driven\n exporters walk this frame instead of the root's children, because a\n selection inside a slot never contains its host and a root walk would\n export nothing. Works for every selection type, not just `RangeSelection`.\n- [`$isSlotHost(node)`](/docs/api/modules/lexical#isslothost) /\n [`$isSlotChild(node)`](/docs/api/modules/lexical#isslotchild) — type guards\n for the [`SlotHostNode`](/docs/api/modules/lexical#slothostnode) /\n [`SlotChildNode`](/docs/api/modules/lexical#slotchildnode) interfaces.\n\n## Slot Order\n\nSlot order is canonical and derived, never stored. Names declared in\n`$config()` (`slots: ['quote', 'attribution']`) sort first in declaration\norder; undeclared names sort after them, lexicographically by UTF-16 code\nunit (plain JavaScript string comparison, locale-independent). `$setSlot`\nre-canonicalizes on every write, so documents normalize on load and\nconcurrent collaborative additions converge to the same order on every\nclient. If presentation order matters, declare the names.\n\n## Rendering\n\nThe reconciler always renders every slot subtree synchronously, but into a\nhidden placeholder container — visibility is the host's explicit decision.\nThere are three ways to attach a slot, all sharing the same contract\n(attaching moves the container to the target, a no-op when it is already\nthere, and reveals it; the container renders as a normal block):\n\n1. **Synchronously in-lexical**: register a `$getSlotTargetElement`\n [`DOMRenderMatch`](/docs/api/modules/lexical_html#domrendermatch)\n override for the host's node class (a\n [DOM render override](../serialization/dom-render.md), not a node\n method — this is an advanced hook). The reconciler consults it whenever\n it creates or reconciles the slot's container and attaches/reveals\n within the same commit — no listener or framework hop. Returning\n `hostDom` reveals the slot in its default slots-first position:\n\n ```ts\n import {domOverride, DOMRenderExtension} from '@lexical/html';\n import {configExtension, defineExtension} from 'lexical';\n\n export const CardExtension = defineExtension({\n dependencies: [\n configExtension(DOMRenderExtension, {\n overrides: [\n domOverride([CardNode], {\n // Reveal the title in its default slots-first position within\n // the same commit that renders it. Returning an element from\n // deeper inside the host's DOM attaches it there instead;\n // $next() defers to lower-priority overrides (default: null,\n // a hidden placeholder).\n $getSlotTargetElement: (node, slotName, hostDom, $next, editor) =>\n hostDom,\n }),\n ],\n }),\n ],\n name: 'card',\n nodes: [CardNode],\n });\n ```\n\n2. **Imperatively**:\n [`mountSlotContainer(editor, nodeKey, slotName, target)`](/docs/api/modules/lexical#mountslotcontainer)\n and\n [`unmountSlotContainer(editor, nodeKey, container)`](/docs/api/modules/lexical#unmountslotcontainer)\n from `lexical` are the framework-independent primitives (e.g. from a\n [mutation listener](/docs/api/modules/lexical#registermutationlistener),\n which fires after the commit). `mountSlotContainer` resolves the container\n against the committed editor state\n ([`editor.getEditorState()`](/docs/api/modules/lexical#geteditorstate)), so\n the model it reads matches the reconciled DOM it reveals;\n `unmountSlotContainer` takes the container you already hold and only touches\n the DOM:\n\n ```ts\n import {mountSlotContainer} from 'lexical';\n\n // e.g. inside an extension's register(editor):\n const unregister = editor.registerMutationListener(\n CardNode,\n (mutations) => {\n for (const [nodeKey, mutation] of mutations) {\n if (mutation === 'destroyed') {\n continue;\n }\n const hostDom = editor.getElementByKey(nodeKey);\n if (hostDom !== null) {\n // Mounting in place: the placeholder is already parked in the\n // host DOM, so this just reveals it in its slots-first position.\n // Any element within the host's DOM works as a target.\n mountSlotContainer(editor, nodeKey, 'title', hostDom);\n }\n }\n },\n {skipInitialization: false},\n );\n ```\n\n `unmountSlotContainer(editor, nodeKey, container)` is the reverse: it\n hides the container and parks it back in the host DOM, for when a mount\n target goes away while the host remains.\n\n3. **From React chrome**: the\n [`useLexicalSlotRef`](/docs/api/modules/lexical_react_useLexicalSlotRef#uselexicalslotref)\n hook from `@lexical/react/useLexicalSlotRef` wraps the imperative pair and returns a\n ref that mounts a slot's container into your component — the usual choice\n for a DecoratorNode host's `decorate()` chrome (whose containers are\n opted back into `contentEditable` automatically, since the decorator DOM\n is non-editable):\n\n```tsx\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {useLexicalSlotRef} from '@lexical/react/useLexicalSlotRef';\n\nfunction PullQuoteComponent({nodeKey}: {nodeKey: NodeKey}) {\n const [editor] = useLexicalComposerContext();\n const quoteRef = useLexicalSlotRef(editor, nodeKey, 'quote');\n const attributionRef = useLexicalSlotRef(\n editor,\n nodeKey,\n 'attribution',\n );\n return (\n
\n
\n
\n
\n );\n}\n```\n\nA `contentEditable=false` ElementNode shell can host React chrome the same\nway (slot containers opt into editing whenever the host DOM is\nnon-editable): the playground's Review demo portals chrome into the host DOM,\nattaches the author slot with `useLexicalSlotRef`, drives an interactive\nstar-rating widget that persists to NodeState, and applies the identical\nhidden-then-attach technique to its `getDOMSlot` children element. Such a shell should call\n[`setDOMUnmanaged(dom)`](/docs/api/modules/lexical#setdomunmanaged) in\n`createDOM` — the portal and the\nattach moves mutate the shell's children from outside the reconciler, and\nthe marker gives the shell the same mutation-observer exemption a\nDecoratorNode's DOM has.\n\n## Editable state\n\nA slot rendered inside a non-editable host (a DecoratorNode, or a\n`contentEditable=false` element shell) would not track the editor's editable\nstate on its own, so the reconciler gives its container an explicit\n`contentEditable` that follows `editor.isEditable()`, and re-renders the islands\nwhenever `setEditable` toggles — so a read-only editor's slots are not left\neditable. No extension is required. Slots always follow the editor; there is\ncurrently no way for a slot to override its own editable state.\n\nA host that attaches its own editable island which is *not* a slot container —\nfor example the Review demo's `getDOMSlot` children element inside its\n`contentEditable=false` shell — opts it into the same behavior with\n[`$markSlotEditable(element, editor)`](/docs/api/modules/lexical#marksloteditable),\nre-applying it from `updateDOM` so an editable toggle reaches the island.\n\n## Editing Behavior\n\n- **Selection never crosses a slot boundary.** Selections are clamped to the\n anchor's slot frame at every entry point (DOM resolution,\n [`$setSelection`](/docs/api/modules/lexical#setselection),\n and point mutation), so a mouse drag and a `shift+arrow` across the\n boundary land on the same clamped result. A focus in a slot of a host is\n moved past the whole host, or to the edge of the host's own children when\n the selection starts inside the host.\n- **Deletion stops at the boundary.** Backspace at the start of a slot and\n forward-Delete at its end are no-ops instead of merging across the virtual\n shadow root.\n- **`Cmd+A` scopes to the slot frame** when the caret is inside one; outside\n slots the default handlers keep the legacy whole-document behavior.\n Progressive expansion (block → enclosing slot frame → document on repeated\n presses) is provided by the opt-in\n [`SelectBlockExtension`](/docs/api/modules/lexical_extension#selectblockextension)\n from `@lexical/extension`.\n- **Generic block conversion skips slot values.** A slot value has no\n parent — its up-link is `$getSlotHost` — so selection-driven block\n converters (`$setBlocksType`, `$wrapNodes`, `$insertList` / `$removeList`,\n the markdown block shortcuts) treat it as ineligible and do nothing rather\n than replace it: the slot assignment is managed by the node or extension\n that owns the slot. Calling `LexicalNode.replace` directly on a slot value\n throws; reassign the slot with `$setSlot` on its host instead.\n- **Slots stay bound to their host through `replace`.** Replacing a slot\n *host* (`host.replace(other)`) does not transfer its slots to the\n replacement — slots are not necessarily portable across node types, so the\n slot map travels with the node, never with its position. If the replaced\n host is reattached in the same update (the\n [`$wrapNodeInElement`](/docs/api/modules/lexical_utils#wrapnodeinelement)\n pattern) it keeps its slots; if it stays detached, its slot subtrees are\n garbage-collected with it. The same applies to anything built on `replace`:\n converting a slot host with `$setBlocksType` produces a slot-less\n replacement block. Move a slot onto another host explicitly with\n `$setSlot`.\n- **A NodeSelection of an element carries its children.** Copy and export\n of a whole-host NodeSelection (e.g. a chrome click that selects \"the whole\n Card\") include the host's body children even though they aren't in the\n selection themselves — the old shell-only output made cut silently lossy.\n This applies only to NodeSelection; a partial RangeSelection over the host\n keeps per-child slicing.\n\n### Traversal is intentionally asymmetric\n\nContent reads include slot subtrees, slots-first:\n[`getTextContent()`](/docs/api/modules/lexical#gettextcontent),\n[`getAllTextNodes()`](/docs/api/modules/lexical#getalltextnodes),\nand the [`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots)\nfamily in `@lexical/utils` count slot content for search, copy, and\naccessibility. Navigation excludes them:\n[`getChildren()`](/docs/api/modules/lexical#getchildren),\n[`getFirstDescendant()`](/docs/api/modules/lexical#getfirstdescendant)\nand friends stay linked-list-only, so caret movement never walks into a slot\nby accident. Choose [`$dfs`](/docs/api/modules/lexical_utils#dfs) or\n[`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots) depending on whether \"this subtree\" should mean the\nnavigable tree or all content.\n\n## Serialization\n\nJSON serialization is automatic in both directions. A host's slots serialize\nunder the reserved `$slots` key on\n[`SerializedLexicalNode`](/docs/api/modules/lexical#serializedlexicalnode)\n(a sibling of\nNodeState's reserved `'$'` key), keyed by slot name:\n\n```json\n{\n \"type\": \"card\",\n \"version\": 1,\n \"$slots\": {\n \"title\": {\"type\": \"paragraph\", \"children\": [], \"version\": 1}\n },\n \"children\": []\n}\n```\n\nParsing re-attaches each subtree with `$setSlot` and throws if `$slots`\nappears on a node that cannot host slots. The `$` prefix keeps the\nframework-owned key from colliding with a subclass that already serializes a\n`slots` property of its own.\n\nHTML serialization is opt-in per host, like NodeState: the exporter never\ndescends into slots on its own. A host's `exportDOM` can emit each slot into\na wrapper using\n[`$appendNodeToHTML`](/docs/api/modules/lexical_html#appendnodetohtml) from\n`@lexical/html`, and a\n[DOM import rule](../serialization/dom-import.md) on the host's\ndistinguishing markup maps the wrappers back through `$setSlot`.\n\n## Collaboration\n\nSlots sync on both the V1 and V2 Yjs bindings through a per-slot-diffed\n`Y.Map` stored under the reserved `__slots` attribute key on the host's shared\ntype (the channel reuses the host's `__slots` field name, which is already\nexcluded from the property sync). Hosts with declared slots create that map\neagerly, so two clients\nconcurrently setting *different* slot names for the first time merge\nper-entry instead of racing. Malformed or hostile remote entries are\nvalidated and skipped.\n\n:::caution\n\nPre-slots clients receiving slot data from upgraded peers will error rather\nthan render it. Enabling slots in long-lived shared documents should be\ngated on all participants running a slots-aware version; new clients\ntolerate unknown slot data going forward.\n\n:::\n\n## Reserved Names\n\nAdding slots reserves a few identifiers that custom node subclasses should\nnot define for their own purposes:\n\n- the `__slots` and `__slotHost` fields on ElementNode / DecoratorNode — the\n `__slots` name is also the collab attribute key for the slots channel, so it\n is reserved on the Yjs shared type too;\n- the `$slots` serialized JSON key.\n\n## Current Limitations\n\n- The caret / NodeCaret APIs throw across a slot boundary (\"no common\n ancestor\"); slot-aware caret traversal is a planned follow-up.\n- Nested slots (a slot whose host is itself slotted) are only handled one\n level deep by the runtime selection comparator.\n- The mixed-version collab caveat above.\n","packages/lexical-website/docs/concepts/node-cloning.md":"# Node Cloning\n\nUnderstanding how to properly clone and modify nodes is crucial for working with Lexical. This guide explains the different cloning mechanisms and when to use each one.\n\n## Types of Node Cloning\n\nLexical provides several ways to clone nodes, each serving a different purpose:\n\n1. `static clone()` - Internal API for state management\n2. `$copyNode()` - Public API for creating new nodes\n3. `getWritable()` - Public API for node modifications\n\n## The `clone` Method\n\n### What is `clone`?\n\nThe `clone` method is a static method that creates the next version of a node. A node that declares [`$config()`](./nodes.mdx) has one synthesized for it and need not implement it — a hand-written `clone` is only required for a node that does not use `$config()`, or whose constructor has required arguments. Either way, it's important to understand that this is an **internal API** used by Lexical's state management system.\n\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n // ✅ Correct implementation\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### When is `clone` Used?\n\n1. **Internal State Management**\n - Used by Lexical internally\n - Part of the editor's state update system\n - Called by `getWritable()`\n\n2. **Node Mutations**\n ```typescript\n // Example of a node method implementation\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n }\n\n node.setData(\"new data\");\n ```\n\n### When NOT to Use `clone`?\n\n```typescript\n// ❌ Never do this\nfunction $duplicateNode(node: MyCustomNode) {\n return MyCustomNode.clone(node); // Don't call clone directly\n}\n```\n\n## The `afterCloneFrom` Method\n\n### What is `afterCloneFrom`?\n\n`afterCloneFrom(prevNode)` runs on every clone, right after it is constructed,\nand copies over whatever the constructor did not. The base implementation\ncarries the node's links to its parent and siblings and its\n[NodeState](./node-state.md), and `ElementNode` and `TextNode` carry their own\nbuilt-in properties such as format, style, and indent. A property that is\ncopied neither by the constructor nor by some `afterCloneFrom` silently\nreverts to its default on the node's next write.\n\n### When you don't need it\n\nWith the modern APIs you usually don't write one at all:\n\n- **Serialization schema.** A property declared as a field in a `$config`\n [`json` schema](./nodes.mdx#creating-custom-nodes-with-a-serialization-schema)\n (`withField(stringValue(), {field: '__label'})`) is carried across the\n clone for you, because the schema says where it is stored. Available in\n Lexical v0.51.0 and later.\n- **NodeState.** State created with `createState` and stored with `$setState`\n is carried by the base `afterCloneFrom`, so a node whose extra data lives\n only in NodeState needs nothing.\n\n```ts\n// At module scope, above the class, so TypeScript checks it against the class\nconst calloutSchema = nodeSchema()({\n label: withField(stringValue(), {field: '__label'}),\n});\n\nclass CalloutNode extends ElementNode {\n __label: string = '';\n\n // No afterCloneFrom: `__label` is declared as a field in calloutSchema, so\n // it is carried across every clone.\n $config() {\n return this.config('callout', {extends: ElementNode, json: calloutSchema});\n }\n}\n```\n\n### When you still need it\n\nOverride `afterCloneFrom` for a property that neither of those covers: a\nfield that isn't in the node's schema, one declared only through accessor\nmethods (see\n[Carrying properties across a clone](../serialization/serialization.md#carrying-properties-across-a-clone)),\nor any property of a node written without a schema. Always call\n`super.afterCloneFrom(prevNode)` first so the inherited properties and\nNodeState are still carried:\n\n```ts\nclass MyCustomNode extends ElementNode {\n __data: string = '';\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__data = prevNode.__data;\n }\n}\n```\n\nLike `clone`, `afterCloneFrom` is called by Lexical; don't call it yourself\nexcept through `super`.\n\n## Using `$copyNode`\n\n### What is `$copyNode`?\n\n`$copyNode` is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node.\nBy default, all properties and `NodeState` will be copied to the new node, and then `resetOnCopyNodeFrom` will be called to\nallow the node to optionally reset certain properties (and NodeState configured with `resetOnCopyNode: true`) to defaults\n(such as the checked state of a `ListItemNode`).\n\n```typescript\n// ✅ Correct: Using $copyNode\nconst copy = $copyNode(existingNode);\n```\n\n### When to Use `$copyNode`?\n\n1. **Creating Duplicates**\n ```typescript\n // ✅ Correct: Duplicating a node\n const duplicate = $copyNode(originalNode);\n someParent.append(duplicate);\n ```\n\n## Using `getWritable`\n\n### What is `getWritable`?\n\n`getWritable` is an internal API used within node method implementations to get a mutable version of a node. Node consumers should use the node's public methods instead.\n\n```typescript\n// ✅ Correct: Implementation of a node method\nclass MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n}\n\n// ✅ Correct: Using the node\nconst node = new MyCustomNode();\nnode.setData(\"new value\");\n```\n\n## Common Patterns\n\n### Modifying Nodes\n\n```typescript\n// ✅ Correct: Modifying a node\nfunction $updateNodeData(node: MyCustomNode, newData: string): MyCustomNode {\n return node.setData(newData);\n}\n\n// ❌ Incorrect: Don't clone manually\nfunction $updateNodeDataWrong(node: MyCustomNode, newData: string): MyCustomNode {\n const clone = MyCustomNode.clone(node);\n clone.setData(newData);\n return clone;\n}\n```\n\n### Copying Nodes\n\n```typescript\n// ✅ Correct: Copying a node\nfunction $duplicateNode(node: MyCustomNode): MyCustomNode {\n return $copyNode(node);\n}\n\n// ❌ Incorrect: Don't use clone\nfunction $duplicateNodeWrong(node: MyCustomNode): MyCustomNode {\n return node.constructor.clone(node);\n}\n```\n\n## Performance Considerations\n\n1. **Referential Integrity**\n - `getWritable()` ensures proper EditorState updates with new clones\n - Prevents \"orphaned\" nodes that won't be rendered\n\n2. **State Management**\n ```typescript\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data; // Properly tracked by editor\n return self;\n }\n }\n ```\n\n## Testing\n\n```typescript\ntest('node modification', async () => {\n await editor.update(() => {\n const node = new MyCustomNode(\"test\");\n \n node.setData(\"new data\");\n \n // ✅ Correct: Use $copyNode for duplication\n const copy = $copyNode(node);\n });\n});\n```\n\n## Related Concepts\n\n- [Editor State](editor-state.md) - How cloning affects editor state\n- [Nodes](nodes.mdx) - Core concepts about Lexical nodes\n\n## Common Questions\n\n**Q: How do I duplicate a node?**\nA: Use `$copyNode(node)` to create a new copy with a new key.\n\n**Q: When should I use clone?**\nA: Never directly. Use `$copyNode()` or `getWritable()` instead. ","packages/lexical-website/docs/concepts/node-replacement.md":"# Node Replacement\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a subclass.\n\n## Use Case\n\n:::note\n\nIn earlier versions of this documentation, \"Node Replacement\" was called \"Node Overrides\".\nWe've changed the name to match the terms used in the implementation.\n\n:::\n\n:::tip\n\nIf your use case only requires adding ad-hoc data to existing nodes, you may be able to use the [NodeState](node-state.md) API instead of subclassing and node replacement.\n\n:::\n\nSome of the most commonly used Lexical Nodes are owned and maintained by the core library. For example, ParagraphNode, HeadingNode, QuoteNode, List(Item)Node etc - these are all provided by Lexical packages, which provides an easier out-of-the-box experience for some editor features, but makes it difficult to override their behavior. For instance, if you wanted to change the behavior of ListNode, you would typically extend the class and override the methods. However, how would you tell Lexical to use *your* ListNode subclass in `ListExtension` instead of using the core ListNode? That's where Node Replacement can help.\n\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a different node class. This can be done through the `nodes` of an extension:\n\n```ts\nconst CustomParagraphExtension = defineExtension({\n name: '@my-app/CustomParagraph',\n nodes: () => [\n // Don't forget to register your custom node separately!\n CustomParagraphNode,\n {\n replace: ParagraphNode,\n with: (node: ParagraphNode) => {\n return $createCustomParagraphNode();\n },\n withKlass: CustomParagraphNode,\n },\n ],\n});\n```\nIn the snippet above,\n- `replace`: Specifies the core node type to be replaced. \n- `with`: Defines a transformation function to replace instances of the original node to the custom node. \n- `withKlass`: This option ensures that behaviors associated with the original node type work seamlessly with the replacement. For instance, node transforms or mutation listeners targeting ParagraphNode will also apply to CustomParagraphNode when withKlass is specified. Without this option, the custom node might not fully integrate with the editor's built-in features, leading to unexpected behavior.\n\nOnce this is done, Lexical will replace all ParagraphNode instances with CustomParagraphNode instances. One important use case for this feature is overriding the serialization behavior of core nodes. Check out the full example below.\n\n## Node Replacement Example\n\nThis example demonstrates using Node Replacement to replace all `ParagraphNode` with a `CustomParagraphNode` that overrides `createDOM`.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-replacement?file=src/main.tsx)\n\n\n","packages/lexical-website/docs/concepts/node-state.md":"# NodeState\n\nThe NodeState API introduced in v0.26.0 allows arbitrary state to be added\nad-hoc to any node in a way that participates with reconciliation, history,\nand JSON serialization.\n\n## Use Case\n\nNodeState allows your application to define keys that can be stored on\nany node with automatic JSON support.\n\n:::tip\n\nYou can even add node state to the RootNode to store document-level metadata.\n\n:::\n\nWith a combination of NodeState and other APIs such as\n[Listeners](listeners.md) or\n[Transforms](transforms.md) you can\nlikely shape the editor to meet your needs without having to do much\n[Node Customization](node-replacement.md).\n\nEven when you are subclassing nodes, using NodeState instead of additional\nproperties to store the node's data can be [more efficient](#efficiency)\nand will save you from writing a lot of boilerplate in the constructor,\nupdateFromJSON, and exportJSON.\n\n## Usage\n\n### createState\n\n[createState](/docs/api/modules/lexical#createstate)\ncreates a\n[StateConfig](/docs/api/modules/lexical#stateconfig)\nwhich defines the key and configuration for your NodeState value.\n\nThe key must be locally unique, two distinct StateConfig must not have the\nsame string key if they are to be used on the same node.\n\nTypical usage will look something like this:\n\n```ts\nconst questionState = createState('question', {\n parse: (v) => (typeof v === 'string' ? v : ''),\n});\n```\n\nThe required `parse` function serves two purposes:\n- It provides a type-safe and runtime-safe way to parse values that were\n serialized to JSON\n- When called with `undefined` (or any invalid value) it should return some\n default value (which may be `undefined` or `null` or any other value you\n choose)\n\nIn this case, the question must be a string, and the default is an\nempty string.\n\nSee the\n[createState](/docs/api/modules/lexical#createstate)\nAPI documentation for more details, there are other optional settings\nthat you may want to define particularly if the value is not a primitive\nvalue such as boolean, string, number, null, or undefined.\n\n:::tip\n\nInstead of writing parse functions by hand, use the\n[serialization schema combinators](/docs/serialization/#declarative-serialization-schemas-with-config)\nfrom `lexical`, such as `stringValue`, `numberValue`, `enumValue`,\n`arrayValue`, `objectValue`, and `nullable`. They are the same ones a node's\n`$config` JSON schema uses. A schema is itself a parse function, so it can be\npassed directly as `parse`:\n\n```ts\nimport {arrayValue, createState, stringValue} from 'lexical';\n\nconst questionState = createState('question', {parse: stringValue()});\nconst tagsState = createState('tags', {parse: arrayValue(stringValue())});\n```\n\nBecause `parse` is just a function, the combinators also compose with schema\nlibraries such as [zod](https://zod.dev/), [ArkType](https://arktype.io/),\n[Effect](https://effect.website/), and [Valibot](https://valibot.dev/). Wrap a\nlibrary's validator in a parse function that returns a default for invalid\ninput, or use `transformValue` to refine what a combinator parsed.\n\n:::\n\n### $getState\n\n[$getState](/docs/api/modules/lexical#getstate) gets the\nNodeState value from the given node, or the default if that key was never\nset on the node.\n\n```ts\nconst question = $getState(pollNode, questionState);\n```\n\nSee also\n[$getStateChange](/docs/api/modules/lexical#getstatechange)\nif you need an efficient way to determine if the state has changed on two\nversions of the same node (typically used in updateDOM, but may be useful in\nan update listener or mutation listener).\n\n### $setState\n\n[$setState](/docs/api/modules/lexical#setstate) sets the\nNodeState value on the given node.\n\n```ts\nconst question = $setState(\n pollNode,\n questionState,\n 'Are you planning to use NodeState?',\n);\n```\n\n:::tip\n\nThe last argument is a ValueOrUpdater, just like with React's useState\nsetters. If you use an updater function and the value does not change,\nthe node and its NodeState *won't* be marked dirty.\n\n:::\n\n## Serialization\n\nThe NodeState for a node, if any values are set to non-default values, is\nserialized to a record under a single\n[NODE_STATE_KEY](/docs/api/modules/lexical#node_state_key)\nwhich is equal to `'$'`.\n\n```json\n{\n \"type\": \"poll\",\n \"$\": {\n \"question\": \"Are you planning to use NodeState?\"\n }\n}\n```\n\n:::tip\n\nBy default, it is assumed that your parsed values are JSON serializable,\nbut for advanced use cases you may use values such as Date, Map, or Set\nthat need to be transformed before JSON serialization. See the\n[StateValueConfig](/docs/api/modules/lexical#statevalueconfig)\nAPI documentation.\n\n:::\n\n### Flat serialization with `$config`\n\nNodes that declare a `StateConfig` in [`$config`](nodes.mdx#creating-custom-nodes-with-config-and-nodestate)\nwith `flat: true` lift that key to the top level of the serialized node\ninstead of nesting it under `'$'`. This makes the JSON shape identical\nto a legacy node that stored the value as a `__property` instance\nvariable, so existing payloads continue to round-trip after the node is\nmigrated to NodeState.\n\nFor example, a `ColoredNode` that extends `TextNode` and declares a flat\n`color` state (see [Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\n$config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n}\n```\n\nserializes as:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"color\": \"red\"\n}\n```\n\nA non-flat (default) state on the same node would instead appear under\n`'$'`:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"$\": {\n \"color\": \"red\"\n }\n}\n```\n\nIn both cases, a key is only emitted when the current value is not equal\nto the default returned by its `parse` function — see\n[Efficiency](#efficiency).\n\n:::note\n\nDon't reuse a flat key that a superclass already serializes (e.g. `text`\non `TextNode`).\n\n:::\n\n### Upgrading a legacy JSON property to NodeState\n\nA node that stores data as a `__property` instance variable with custom\n`exportJSON`/`importJSON`/`updateFromJSON` can be migrated to NodeState\nwith `flat: true` without changing its serialized JSON shape.\n\nBefore — `ColoredNode` with a `__color` property and hand-written\nserialization (see the full legacy example in\n[Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\nexport type SerializedColoredNode = Spread<\n {color?: string},\n SerializedTextNode\n>;\n\nexport class ColoredNode extends TextNode {\n __color: string;\n\n constructor(text: string = '', color: string = DEFAULT_COLOR, key?: NodeKey) {\n super(text, key);\n this.__color = color;\n }\n\n static getType(): string {\n return 'colored';\n }\n\n static clone(node: ColoredNode): ColoredNode {\n return new ColoredNode(node.__text, node.__color, node.__key);\n }\n\n static importJSON(serializedNode: SerializedColoredNode) {\n return new ColoredNode().updateFromJSON(serializedNode);\n }\n\n updateFromJSON(serializedNode: SerializedColoredNode) {\n const self = super.updateFromJSON(serializedNode);\n self.__color =\n typeof serializedNode.color === 'string'\n ? serializedNode.color\n : DEFAULT_COLOR;\n return self;\n }\n\n exportJSON(): SerializedColoredNode {\n return {\n ...super.exportJSON(),\n color: this.__color === DEFAULT_COLOR ? undefined : this.__color,\n };\n }\n}\n```\n\nAfter — same on-the-wire JSON, no hand-written serialization:\n\n```ts\nconst colorState = createState('color', {\n parse: (v) => (typeof v === 'string' ? v : DEFAULT_COLOR),\n});\n\nexport class ColoredNode extends TextNode {\n $config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n }\n}\n```\n\nNo `exportJSON`, `importJSON`, `updateFromJSON`, `clone`, or\n`afterCloneFrom` override is needed: `$config` installs `clone` and\n`importJSON`, and the base `exportJSON`/`updateFromJSON`/`afterCloneFrom`\non `LexicalNode`/`TextNode` already round-trip NodeState. Read the color\nvia `$getState(node, colorState)` and write it via\n`$setState(node, colorState, value)` instead of `node.__color`.\n\n:::tip\n\nFor a seamless migration, keep the JSON key name the same — for a flat\nstate, that's the first argument to `createState`. Migrating from a\nnon-flat NodeState to a flat NodeState also works: state that appears\nunder the `$` (`NODE_STATE_KEY`) is still parsed even when the state is\nconfigured as flat, and the flat value takes precedence when both are\npresent.\n\n:::\n\n## Efficiency\n\nNodeState uses a copy-on-write scheme to manage each node's state. If\nnone of the state has changed, then the NodeState instance will be\nshared across multiple versions of that node.\n\n:::info\n\nIn a given reconciliation cycle, the first time a Lexical node is marked dirty\nvia `getWritable` will create a new instance of that node. All properties\nof the previous version are set on the new instance. NodeState is stored\nas a single property, and no copying of the internal state is done\nuntil the NodeState itself is marked writable.\n\n:::\n\nWhen serializing to JSON, each key will only be stored if the value\nis not equal to the default value. This can save quite a lot of space\nand bandwidth.\n\nParsing and serialization is only done at network boundaries, when\nintegrating with JSON or Yjs. When a value changes from an external\nsource, it is only parsed once the first time it is read.\nValues that do not come from external sources are not parsed, and\nvalues that are not used are never parsed.\n\n## Capabilities\n\nCurrent:\n\n- Allows you to define and add state to any node\n- Serializes that state automatically in the node's JSON, supporting\n versioning and copy+paste\n- Works with the reconciler, TextNodes with differing state will not\n be implicitly merged\n- @lexical/yjs support, NodeState will be automatically synchronized\n like any other property\n- NodeState values that are not used will simply pass-through, making\n it a bit easier for situations where multiple configurations are used\n on the same data (e.g. older and newer versions of your editor,\n a different set of plugins based on context, etc.).\n- Pre-registration system for nodes to declare expected state\n and serialize them as top-level properties (`flat`) with `$config`\n (see [#7260](https://github.com/facebook/lexical/issues/7260)).\n- Can be integrated with\n [DOMRenderExtension](../serialization/dom-render.md) for editor\n rendering and HTML export\n- Can be integrated with\n [DOMImportExtension](../serialization/dom-import.md) for HTML import\n\nFuture:\n\n- Does not yet support direct integration with Yjs, e.g.\n you can not store a Y.Map as a NodeState value\n (see [#7293](https://github.com/facebook/lexical/issues/7293))\n\n## Node State Style Example\n\nThis example demonstrates an advanced use case of storing a style object on TextNode using NodeState.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-state-style?file=src/main.tsx)\n\n\n","packages/lexical-website/docs/concepts/one-lexical-per-app.md":"---\nsidebar_label: One Lexical per app\n---\n\n# One Lexical per app\n\n`lexical` is effectively a singleton **within one app**: an app must resolve\nexactly **one** copy of `lexical`, and one copy of each `@lexical/*` package it\nuses. Two copies in the same bundle do not merely waste bytes — they break the\neditor in ways whose error messages point nowhere near the real cause.\n\nThe practical consequence, covered in [Publishing a library](#publishing-a-library)\nbelow: **a library built on Lexical declares `lexical` and the `@lexical/*`\npackages it imports as `peerDependencies`, never as `dependencies`. The\napplication brings its own Lexical.**\n\n:::note\n\nThis page is about npm `peerDependencies` in your `package.json`. Extensions\nhave their own, unrelated notion of\n[peer dependencies](../extensions/peer-dependencies.md) — optional links between\nextensions inside one editor.\n\n:::\n\n## The boundary is the app, not the page\n\nSeveral self-contained apps can share a page, each with its own bundled copy of\nLexical, and that is fine — a CMS page with two independently deployed widgets\non it, or a micro-frontend setup, does not have a bug just because two copies of\n`lexical` are loaded. Lexical anticipates this: `isLexicalEditor()` is an\n`instanceof` check specifically \"to prevent issues with multiple embedded\nLexical installations\", and an editor is tagged on its own root element rather\nthan in any page-global registry, so each app's editors resolve to that app's\nLexical and ignore the others.\n\nWhat those apps cannot do is interoperate. Two copies have no compatible API\nsurface between them, so treat each as a sealed island:\n\n- do not pass nodes, editors, `EditorState` objects, selections or commands\n across the boundary — pass serialized JSON or HTML, which is data rather than\n identity;\n- a plugin, node package or shared editor config must be bundled with the app it\n serves, not shared as a live import between apps;\n- `@lexical/react` context does not cross the boundary either, since the context\n object itself comes from one copy.\n\nThe rest of this page is about the failure case: two copies **inside one app**,\nwhere code from copy A is expected to work with an editor from copy B.\n\n## Why one copy per app\n\nLexical keeps state at module scope, and identifies things by reference rather\nthan by name. Both assumptions hold only within a single copy of the module.\n\n- **The active editor is module state.** `activeEditor`, `activeEditorState`\n and `isReadOnlyMode` live at module scope in `LexicalUpdates.ts`, and every\n `$` function reads them. `editor.update()` in copy A sets copy A's variables;\n a `$` function imported from copy B reads copy B's, which are still `null`\n ([Editor State](editor-state.md)).\n- **Node classes are compared by identity.** Node registration and the\n `instanceof LexicalNode` checks compare class references. A node that extends\n `LexicalNode` from copy A is not, as far as copy B is concerned, a\n `LexicalNode` at all — even though both classes have the same name and come\n from the same published version ([Nodes](nodes.mdx)).\n- **Commands are object identities.** `createCommand()` returns a fresh `{type}`\n object, and `registerCommand`/`dispatchCommand` match on that object, not on\n its `type` string. Two copies of `lexical` export two distinct\n `FORMAT_TEXT_COMMAND` objects, so a dispatch from one never reaches a listener\n registered with the other ([Commands](commands.md)).\n\nOn top of that, two copies are usually two *versions*, which is API drift inside\na single editor: half your plugins were compiled against a different API and\nserialization format than the editor running them, and the mismatch surfaces\nonly at runtime, on the paths that happen to differ.\n\n## Symptoms of a duplicated Lexical\n\nThe errors are unhelpfully literal — a class that plainly does implement\n`getType()` is reported as not implementing it, because the check is running\nagainst the other copy:\n\n```\nLexicalNode: Node FooNode does not implement .getType().\n\nCreate node: Type heading in node HeadingNode does not match registered node\nHeadingNode with the same type\n\ncreateEditor: nodes[0] FooNode (type foo) is not a constructor that subclasses\nLexicalNode from the lexical package used by this editor (0.50.0)\n\nUnable to find an active editor state. State helpers or node methods can only be\nused synchronously during the callback of editor.update(), editor.read(), or\neditorState.read(). Detected on the page: 0 compatible editor(s) with version\n0.50.0 and incompatible editors with versions 0.49.0\n```\n\nThat last sentence is Lexical telling you directly that it found editors built\nfrom another copy — a version different from its own, or the same version marked\n`(separately built, likely a bundler configuration issue)`. Note that this\ndiagnostic scans the whole page, so a genuinely separate app that ships its own\nLexical is counted there too; it is evidence of a bug only when those editors\nwere supposed to be part of *your* app.\n\nSilent failures look like: a command that dispatches but never fires its\nlistener, `$getSelection()` returning `null` inside an update, or a custom node\nrendering as plain text after a copy/paste. Real reports of this failure mode:\n[#4225](https://github.com/facebook/lexical/issues/4225) and\n[#7819](https://github.com/facebook/lexical/issues/7819).\n\n## Publishing a library\n\nIf you publish a package that imports from `lexical` or `@lexical/*` — a plugin,\na node package, a shared editor config, an in-house wrapper in a monorepo — put\nthose packages in `peerDependencies`, and in `devDependencies` so you can still\nbuild and test:\n\n```json\n{\n \"name\": \"my-lexical-plugin\",\n \"peerDependencies\": {\n \"lexical\": \">=0.50.0\",\n \"@lexical/react\": \">=0.50.0\",\n \"@lexical/utils\": \">=0.50.0\"\n },\n \"devDependencies\": {\n \"lexical\": \"0.50.0\",\n \"@lexical/react\": \"0.50.0\",\n \"@lexical/utils\": \"0.50.0\"\n }\n}\n```\n\nNotes on the ranges:\n\n- Lexical is pre-1.0, so `^0.50.0` means `>=0.50.0 <0.51.0` — a caret peer range\n locks your users out of the next release. Prefer an open `>=` range (or an\n explicit `>=0.50.0 <1.0.0`) so an app can upgrade Lexical without waiting for\n you.\n- Mark a peer optional with\n [`peerDependenciesMeta`](https://docs.npmjs.com/cli/configuring-npm/package-json#peerdependenciesmeta)\n when the import is behind an opt-in entry point, the way this repo's own\n packages mark `typescript` optional.\n- Do not add `lexical` to `dependencies` \"just so it installs\". That is exactly\n what pins a second copy under `node_modules/your-lib/node_modules/lexical` as\n soon as your range and the app's range disagree.\n\n## Application setup\n\nThe application owns the version, and every Lexical package it installs moves\ntogether:\n\n- Install `lexical` and each `@lexical/*` package you use **at the same\n version**. Published `@lexical/*` packages depend on the exact matching\n `lexical` version (the monorepo's `workspace:*` is rewritten to an exact\n version at publish time), so `@lexical/react@0.50.0` beside `lexical@0.49.0`\n guarantees a nested second copy.\n- Verify there is only one **per app**, from the app root:\n\n ```sh\n npm ls lexical @lexical/react # or: pnpm why lexical / yarn why lexical\n ```\n\n More than one resolved version, or a path with a nested `node_modules/lexical`\n in it, is the bug.\n- In a monorepo or a linked-package setup (`npm link`, `pnpm link`, a Yalc\n copy), the linked library resolves Lexical from *its own* `node_modules` and\n duplicates are the default rather than the exception. Deduplicate explicitly:\n hoist the dependency to the workspace root, or force resolution with\n [pnpm `overrides`](https://pnpm.io/settings#overrides), Yarn `resolutions`, or\n `npm dedupe`.\n- Bundlers can also be told to collapse duplicates — Vite\n [`resolve.dedupe`](https://vite.dev/config/shared-options.html#resolve-dedupe),\n webpack `resolve.alias` pointing each package at one path:\n\n ```js\n // vite.config.js\n export default {\n resolve: {dedupe: ['lexical', '@lexical/react', '@lexical/utils']},\n };\n ```\n\n Treat that as a safety net, not a fix: it collapses copies that are already\n version-compatible, and cannot rescue two genuinely different versions.\n- Duplication does not always come from the dependency tree: importing Lexical\n through both `import` and `require` pulls in the ESM and the CJS build of the\n *same* version, which are still two copies. The\n [React FAQ](../react/faq.md#lexicalcomposercontextuselexicalcomposercontext-cannot-find-a-lexicalcomposercontext)\n covers how this one shows up in `@lexical/react`.\n","packages/lexical-website/docs/concepts/read-only.md":"\n\n# Read Mode / Edit Mode\n\nLexical supports two modes:\n\n- Read mode\n- Edit mode\n\nThe default behavior for Lexical is edit mode, or more accurately not read only mode. Under-the-hood, the main\nimplementation detail is that the `contentEditable` is being set to `\"false\"` or `\"true\"` depending on the mode.\nSpecific plugins can listen to the mode change too – allowing them to customize parts of the UI depending on the\nmode.\n\n## Setting the mode\n\nIn order to set the mode, this can be done on creation of the editor, with the\n`editable` property of your app's extension:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [RichTextExtension],\n editable: false,\n name: '@my-app/editor',\n }),\n);\n```\n\nWith React, pass the same extension to ``:\n\n```jsx\n\n ...\n\n```\n\nAfter an editor is created, the mode can be changed imperatively:\n\n```js\neditor.setEditable(true);\n```\n\n## Reading the mode\n\nIn order to find the current mode of the editor you can use:\n\n```js\nconst isEditable = editor.isEditable(); // Returns true or false\n```\n\nYou can also get notified when the editor's read only mode has changed:\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (isEditable) => {\n // The editor's mode is passed in!\n console.log(isEditable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\nIn an extension, depend on\n[`WatchEditableExtension`](/docs/api/modules/lexical_extension#watcheditableextension),\nwhose output is a signal holding the current editable state, instead of\nregistering the listener yourself.\n","packages/lexical-website/docs/concepts/selection.md":"# Selection\n\n## Types of selection\n\nLexical's selection is part of the `EditorState`. This means that for every update, or change to the editor, the\nselection always remains consistent with that of the `EditorState`'s node tree.\n\nIn Lexical, there are four types of selection possible:\n\n- `RangeSelection`\n- `NodeSelection`\n- `TableSelection` (implemented in `@lexical/table`)\n- `null`\n\nIt is possible, but not generally recommended, to implement your own selection types that implement `BaseSelection`.\n\n### `RangeSelection`\n\nThis is the most common type of selection, and is a normalization of the browser's DOM Selection and Range APIs.\n`RangeSelection` consists of three main properties:\n\n- `anchor` representing a `RangeSelection` point\n- `focus` representing a `RangeSelection` point\n- `format` numeric bitwise flag, representing any active text formats\n\nBoth the `anchor` and `focus` points refer to an object that represents a specific part of the editor. The main properties of a `RangeSelection` point are:\n\n- `key` representing the `NodeKey` of the selected Lexical node\n- `offset` representing the position from within its selected Lexical node. For the `text` type this is the character, and for the `element` type this is the child index from within the `ElementNode`\n- `type` representing either `element` or `text`.\n\n### `NodeSelection`\n\nNodeSelection represents a selection of multiple arbitrary nodes. For example, three images selected at the same time.\n\n- `getNodes()` returns an array containing the selected LexicalNodes\n\n### `TableSelection`\n\nTableSelection represents a grid-like selection like tables. It stores the key of the parent node where the selection takes place and the start and end points.\n`TableSelection` consists of three main properties:\n\n- `tableKey` representing the parent node key where the selection takes place\n- `anchor` representing a `TableSelection` point\n- `focus` representing a `TableSelection` point\n\nFor example, a table where you select row = 1 col = 1 to row 2 col = 2 could be stored as follows:\n- `tableKey = 2` table key\n- `anchor = 4` table cell (key may vary)\n- `focus = 10` table cell (key may vary)\n\nNote that `anchor` and `focus` points work the same way as `RangeSelection`.\n\n### `null`\n\nThis is for when the editor doesn't have any active selection. This is common for when the editor has been blurred or when selection\nhas moved to another editor on the page. This can also happen when trying to select non-editable components within the editor space.\n\n## Working with selection\n\nSelection can be found using the `$getSelection()` helper, exported from the `lexical` package. This function can be used within\nan update, a read, or a command listener.\n\n:::tip\n\nTo walk the document from a selection point — or to write a traversal that\nhandles empty nodes and collapsed selections correctly — see\n[Node Traversals with NodeCaret](./traversals.md).\n`$caretRangeFromSelection(selection)` converts a `RangeSelection` into the\ncaret range that traversal API works with, and\n`$setSelectionFromCaretRange(range)` converts back.\n\n:::\n\n```js\nimport {$getSelection, SELECTION_CHANGE_COMMAND} from 'lexical';\n\neditor.update(() => {\n const selection = $getSelection();\n});\n\neditorState.read(() => {\n const selection = $getSelection();\n});\n\n// SELECTION_CHANGE_COMMAND runs before reconciliation in the pending update.\neditor.registerCommand(SELECTION_CHANGE_COMMAND, () => {\n const selection = $getSelection();\n});\n```\n\nIn some cases you might want to create a new type of selection and set the editor selection to\nbe that. This can only be done in update or command listeners.\n\n```js\nimport {$setSelection, $createRangeSelection, $createNodeSelection} from 'lexical';\n\neditor.update(() => {\n // Set a range selection\n const rangeSelection = $createRangeSelection();\n $setSelection(rangeSelection);\n\n // You can also indirectly create a range selection, by calling some of the selection\n // methods on Lexical nodes.\n const someNode = $getNodeByKey(someKey);\n\n // On element nodes, this will create a RangeSelection with type \"element\",\n // referencing an offset relating to the child within the element.\n // On text nodes, this will create a RangeSelection with type \"text\",\n // referencing the text character offset.\n someNode.select();\n someNode.selectPrevious();\n someNode.selectNext();\n\n // You can use this on any node.\n someNode.selectStart();\n someNode.selectEnd();\n\n // Set a node selection\n const nodeSelection = $createNodeSelection();\n // Add a node key to the selection.\n nodeSelection.add(someKey);\n $setSelection(nodeSelection);\n\n // You can also clear selection by setting it to `null`.\n $setSelection(null);\n});\n```\n\n## Focus\n\nYou may notice that when you issue an `editor.update` or\n`editor.dispatchCommand` then the editor can \"steal focus\" if there is\na selection and the editor is editable. This is because the Lexical\nselection is reconciled to the DOM selection during reconciliation,\nand the browser's focus follows its DOM selection.\n\nIf you want to make updates or dispatch commands to the editor without\nchanging the selection, can use the `SKIP_DOM_SELECTION_TAG` update tag\n(added in v0.22.0):\n\n```js\n// Call this from an editor.update or command listener\n$addUpdateTag(SKIP_DOM_SELECTION_TAG);\n```\n\nIf you want to add this tag during processing of a `dispatchCommand`,\nyou can wrap it in an `editor.update`:\n\n```js\n// NOTE: If you are already in a command listener or editor.update,\n// do *not* nest a second editor.update! Nested updates have\n// confusing semantics (dispatchCommand will re-use the\n// current update without nesting)\neditor.update(() => {\n $addUpdateTag(SKIP_DOM_SELECTION_TAG);\n editor.dispatchCommand(/* … */);\n});\n```\n\n`SKIP_DOM_SELECTION_TAG` does not apply to the initial editor state setup\n(the `$initialEditorState` property of the root extension, or\n`initialConfig.editorState` with the legacy `LexicalComposer`). On first mount the editor still scrolls\nto and focuses the initial selection. To prevent that, call\n`$setSelection(null)` inside your initial state setup function:\n\n```js\nconst editor = buildEditorFromExtensions({\n name: '[root]',\n // ...\n $initialEditorState: () => {\n // ... build your initial nodes ...\n $setSelection(null);\n },\n});\n```\n\nIf you have to support older versions of Lexical, you can mark the editor\nas not editable during the update or dispatch.\n\n```js\n// NOTE: This code should be *outside* of your update or command listener, e.g.\n// directly in the DOM event listener\nconst prevEditable = editor.isEditable();\neditor.setEditable(false);\neditor.update(\n () => {\n // run your update code or editor.dispatchCommand in here\n }, {\n onUpdate: () => {\n editor.setEditable(prevEditable);\n },\n },\n);\n```\n\n## Reading selection across a shadow boundary\n\nIf your plugin reads the DOM selection directly — through\n`Selection.anchorNode`, `Selection.getRangeAt(0)`, or similar — and the\neditor's `contentEditable` lives inside a `ShadowRoot`, the browser retargets\nthose reads to the shadow host. See\n[Shadow DOM and iframes](./shadow-dom.md) for the shadow-aware helpers\n(`getDOMSelectionPoints`, `getDOMSelectionRange`, etc.) that return the\nun-retargeted boundary points; they fall through to the standard reads in the\nplain light DOM, so there's nothing to do until you actually mount the editor\nin a shadow tree.\n\n### Selection change timing\n\n`SELECTION_CHANGE_COMMAND` runs **before reconciliation**, in a writable update,\nfor native, programmatic, and non-range selection changes. `$getSelection()`\nreturns the pending selection; `$getPreviousSelection()` returns the selection\nfrom the last committed state. A listener can normalize the selection or edit\nnodes before that same update commits. Listeners that change the selection may\ncause another notification before commit; they must converge.\n\nThis covers programmatic changes such as `node.select()`, which notify without\nwaiting for a DOM `selectionchange` event, and non-range selections such as\n`NodeSelection` and `TableSelection`, as well as native range selections.\n\nSelection listeners use the update's normal error handling. A throwing listener\nreports through `onError` and can abort the entire pending update, including the\nedit that triggered the notification and any other edits batched into that\ncommit, just like an explicit command dispatch inside that update. Because a\nprogrammatic selection change also notifies, a listener error can abort content\nedits made in the same update. Listener edits do not have a separate rollback\nscope.\n\nThe DOM is not guaranteed to match the pending state, even for a `NodeSelection`.\nNew nodes may not have an element yet, and DOM ranges, layout, and focus may\nstill reflect the previous state. Schedule DOM-dependent work after the update\nand read the reconciled state there:\n\n```ts\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n $onUpdate(() => {\n editor.read('latest', () => {\n // Read $getSelection(), look up elements, or position floating UI here.\n });\n });\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport `$onUpdate` and `COMMAND_PRIORITY_LOW` from `lexical`. Read selection and\nnodes inside the callback rather than capturing mutable pending objects.\n`registerUpdateListener` is another option for UI that must respond to every\ncommit, including content changes that do not change the selection. Updates\nusing `SKIP_DOM_SELECTION_TAG` still deliberately leave the browser selection\nunsynchronized.\n\n#### Update tags and local edits\n\nThe notification belongs to the pending update and inherits its tags. A listener\ncan inspect them with `$hasUpdateTag`. In particular, Yjs does not sync content\nedits back to peers when the update is tagged `COLLABORATION_TAG` or\n`HISTORIC_TAG`; history also treats `HISTORIC_TAG` as replaying an existing entry.\nThis applies to content edits made by selection listeners in those updates.\n\nListeners that only apply to local editing should skip those tagged updates. If\na remote change or undo must trigger an independent local content edit, schedule\nit after the tagged commit with `$onUpdate`, then start a fresh `editor.update`:\n\n```ts\nconst $applyLocalEdit = () => {\n // Read the current selection and nodes, then apply a convergent local edit.\n};\n\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n if ($hasUpdateTag(COLLABORATION_TAG) || $hasUpdateTag(HISTORIC_TAG)) {\n $onUpdate(() => editor.update($applyLocalEdit));\n } else {\n $applyLocalEdit();\n }\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport the tags and `$hasUpdateTag` from `lexical`. Re-read the state in the fresh\nupdate; it has its own collaboration and undo behavior. Calling `editor.update`\ndirectly inside the command listener queues a nested update that still belongs\nto the same tagged commit.\n\nAutomatic range and cleared-selection notifications require a connected editor\nroot. Changes committed while those notifications are skipped advance the\nselection baseline and are not replayed when the root reconnects. Non-range\nselections continue to notify in unmounted and headless editors,\nwith the same pre-reconciliation timing. Native dirty-selection notifications\nmay fire even when the selection compares equal to the previous selection.\n","packages/lexical-website/docs/concepts/shadow-dom.md":"---\nsidebar_label: Shadow DOM and iframes\n---\n\n# Shadow DOM and iframes\n\nA Lexical editor works when its `contentEditable` lives inside an **open**\n[DOM `ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) (for\nexample inside a [web component](https://developer.mozilla.org/docs/Web/API/Web_components))\nor inside an `\n\n## Sharing one Yjs document between editors\n\nBy default a binding uses the `XmlText` shared type named `root` on the Yjs\n`Doc`, so each editor needs its own document. Two options let several editors\nlive in one document instead, which is what applications like collaborative\nsticky notes or comment threads usually want:\n\n- `rootName` picks a different top-level shared type, one per editor:\n\n```jsx\n\n```\n\n- `getXmlText` resolves the root yourself, for roots that are not top-level\n shared types (for example an `XmlText` stored in a `Y.Map`). It takes\n precedence over `rootName`:\n\n```jsx\nconst getXmlText = useCallback(\n (doc) => doc.getMap('notes').get(noteId),\n [noteId],\n);\n\n\n```\n\nGive each editor its own `id`, as above: the `id` keys the document map and the\nremote-cursor highlight registry, both of which are shared across the page, so\ntwo editors mounted under one `id` overwrite each other's entries.\n\nBoth options are also available on `createYjsBinding` for non-React usage.\n\n:::warning\n\nThe root is chosen when the binding is created, and a mounted editor cannot be\nrepointed at another root: changing `rootName` or `getXmlText` afterwards has no\neffect. To switch documents, remount the **editor** — put a `key` that changes\nwith the document on the component that owns the `LexicalComposer`. Remounting\nonly the plugin is not enough: the editor would keep the previous document's\ncontent and write it into the newly selected root.\n\n:::\n\n`getXmlText` runs while the binding is constructed, before the provider has\nsynced, so it has to resolve the root from whatever the local `Doc` holds at\nthat moment — reaching into a `Y.Array` that the server has not sent yet throws.\nEither mount the editor only once the note exists locally, or have the callback\ncreate the missing shared type. Write it to be idempotent: it can run more than\nonce for one editor (React StrictMode double-invokes render, and a remount\nbuilds a new binding), and a callback that unconditionally stores a new\n`XmlText` would throw away what the previous call stored.\n\nThe returned `XmlText` is checked to be an `XmlText` that is integrated into the\ndocument; that it is not already driving another live binding is yours to\nguarantee, since a second binding over one root takes over the collab nodes\ncached on its shared types.\n\nThe experimental `CollaborationPluginV2__EXPERIMENTAL` (and\n`createBindingV2__EXPERIMENTAL`) take the same two options, except that its\nroot is an `XmlElement`, so the callback is named `getXmlElement`. Create that\nelement as `new Y.XmlElement()` without a `nodeName`, which is how the root is\nrecognized.\n\n## Building collaborative plugins\n\n[Lexical Playground](https://playground.lexical.dev/) features set of the collaboration enabled plugins that integrate with primary document via `useCollaborationContext()` hook. Notable mentions:\n\n- [`CommentPlugin`](https://github.com/facebook/lexical/tree/main/packages/lexical-playground/src/plugins/CommentPlugin) - features use of the separate provider and Yjs room to sync comments.\n- [`ImageComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/ImageComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested caption editor.\n- [`PollOptionComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/PollComponent.tsx) - showcases poll implementation using `name` from the collaboration context.\n- [`StickyComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/StickyComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested editor as well as sticky note position real-time sync.\n\n:::note\n\nWhile these \"playground\" plugins aren't production ready - they serve as a great example of collaborative Lexical capabilities as well as provide a good starting point.\n\n:::\n\n## Custom node property syncing\n\n`@lexical/yjs` syncs custom node properties by constructing a fresh node instance and inspecting its **own enumerable properties**. This means every property that should be synced across peers must be assigned in the constructor, even if the initial value is `undefined`.\n\n:::warning\n\nDeclaring a class property with TypeScript's optional syntax (`foo?: Type`) does **not** guarantee the property exists as an own enumerable property on the instance. Under TypeScript's default compilation settings (target < ES2022 without `useDefineForClassFields`), such declarations produce no initialization code.\n\n:::\n\n### What to do\n\nAlways initialize every node property in the constructor. Conditional initialization such as `if (someValue !== undefined) this.__someValue = someValue` is not enough, because the default construction path still needs to create the property.\n\nFor example:\n\n```ts\n// ✅ Correct — property is guaranteed to be an own property\nclass MyNode extends ElementNode {\n __someValue: string | undefined;\n\n constructor(someValue?: string, key?: NodeKey) {\n super(key);\n this.__someValue = someValue; // explicitly initialized\n }\n}\n\n// ❌ Incorrect — property may not exist as an own property\nclass MyNode extends ElementNode {\n __someValue?: string; // optional syntax without initialization\n\n constructor(key?: NodeKey) {\n super(key);\n // __someValue is never assigned → won't be synced via yjs\n }\n}\n```\n\nIf you use [`NodeState`](../concepts/node-state.md) for your custom properties, this concern does not apply. `NodeState` values are synced correctly without relying on constructor-created enumerable properties.\n\n## Yjs providers\n\nSetting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. Providers manage all that for you and are the perfect starting point for your collaborative app.\n\nSee [Yjs Website](https://docs.yjs.dev/ecosystem/connection-provider) for the list of the officially endorsed providers. Although it's not an exhaustive one.\n","frontmatter":{"sidebar_position":1},"isInternal":false,"tokens":2689,"sizeBytes":11650},{"name":"_category_.json","path":"packages/lexical-website/docs/concepts/_category_.json","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/_category_.json","title":"Concepts Skill","category":"anthropic-skill","format":"json","content":"{\n \"label\": \"Concepts\",\n \"position\": 3\n}\n","frontmatter":{"label":"Concepts","position":3},"isInternal":false,"tokens":17,"sizeBytes":43},{"name":"commands.md","path":"packages/lexical-website/docs/concepts/commands.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/commands.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"\n\n# Commands\n\nCommands are a very powerful feature of Lexical that lets you register listeners for events like `KEY_ENTER_COMMAND` or `KEY_TAB_COMMAND` and contextually react to them _wherever_ & _however_ you'd like.\n\nThis pattern is useful for building [`Toolbars`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) or complex extensions and nodes such as [tables](https://github.com/facebook/lexical/tree/main/packages/lexical-table) which require special handling for `selection`, `keyboard events`, and more.\n\nWhen registering a `command` you supply a `priority` and can return `true` to mark it as \"handled\", which stops other listeners from receiving the event. If a command isn't handled explicitly by you, it's likely handled by default in [`RichTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-rich-text/src/index.ts) or [`PlainTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-plain-text/src/index.ts).\n\n## `createCommand(...)`\n\nYou can view the core commands in the [`lexical` API reference](/docs/api/modules/lexical#commands). Other packages define their own, listed under Commands in each package's API reference, such as [`TOGGLE_LINK_COMMAND`](/docs/api/modules/lexical_link#toggle_link_command) in `@lexical/link`. If you need a custom command for your own use case, check out the typed `createCommand(...)` function.\n\n```js\nconst HELLO_WORLD_COMMAND: LexicalCommand = createCommand('HELLO_WORLD');\n\neditor.registerCommand(\n HELLO_WORLD_COMMAND,\n (payload: string) => {\n console.log(payload); // Hello World!\n return false;\n },\n COMMAND_PRIORITY_EDITOR,\n);\n\neditor.dispatchCommand(HELLO_WORLD_COMMAND, 'Hello World!');\n```\n\n## `editor.dispatchCommand(...)`\n\nCommands can be dispatched from anywhere you have access to the `editor` such as a Toolbar Button, an event listener, or an extension, but most of the core commands are dispatched from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\nCalling `dispatchCommand` will implicitly call `editor.update` to trigger its command listeners if it was not called from inside `editor.update`.\n\nDon't dispatch a command from inside a read-only context such as\n`editor.read(fn)` or `editorState.read(fn)`. Command listeners usually change\nthe editor, so Lexical runs them in a separate writable update and\ndevelopment builds log a warning when they detect this. Dispatch after the\nread returns instead.\n\n```js\neditor.dispatchCommand(command, payload);\n```\n\nThe `payload`s are typed via the `createCommand(...)` API, but they're usually a DOM `event` for commands dispatched from an event listener.\n\nHere are some real examples from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\n```js\neditor.dispatchCommand(KEY_ARROW_LEFT_COMMAND, event);\n// ...\neditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic');\n```\n\nAnd another example from the [`ToolbarPlugin`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) in our Playground.\n\n```js\nconst formatBulletList = () => {\n editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND);\n};\n```\n\nWhich is later handled by [`ListExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-list/src/LexicalListExtension.ts) to insert the list into the editor.\n\n```js\neditor.registerCommand(\n INSERT_UNORDERED_LIST_COMMAND,\n () => {\n $insertList('bullet');\n return true;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\n## `editor.registerCommand(...)`\n\nYou can register a command from anywhere you have access to the `editor` object, but it's important that you remember to clean up the listener with its remove listener callback when it's no longer needed.\n\nThe command listener will always be called from an `editor.update`, so you may use dollar functions. You should not use\n`editor.update` (and *never* call `editor.read(...)` or `editor.read('force-commit', ...)`) synchronously from within a command listener. It is safe to call\n`editor.read('latest', ...)` or `editor.getEditorState().read` if you need to read the previous state after updates have already been made.\n\n```js\nconst removeListener = editor.registerCommand(\n COMMAND,\n (payload) => boolean, // Return true to stop propagation.\n priority,\n);\n// ...\nremoveListener(); // Cleans up the listener.\n```\n\nThe easiest way to get clean-up right is to register commands from an\n[extension](/docs/extensions/defining-extensions)'s `register` function and\nreturn the remove callback. The editor calls it when it is disposed. To\nregister several things, combine their callbacks with `mergeRegister` from\n`@lexical/utils`.\n\n```js\nimport {LinkExtension, TOGGLE_LINK_COMMAND} from '@lexical/link';\nimport {COMMAND_PRIORITY_BEFORE_EDITOR, defineExtension} from 'lexical';\n\nexport const LinkLoggerExtension = defineExtension({\n // The command it observes is handled by LinkExtension\n dependencies: [LinkExtension],\n name: '@my-app/LinkLogger',\n register: (editor) =>\n editor.registerCommand(\n TOGGLE_LINK_COMMAND,\n (payload) => {\n console.log('link', payload);\n return false; // let the link extension handle it too\n },\n // LinkExtension handles this command at COMMAND_PRIORITY_EDITOR and\n // returns true, so observe it at the BEFORE variant of that priority.\n COMMAND_PRIORITY_BEFORE_EDITOR,\n ),\n});\n```\n\nA listener that only observes a command, like this one, needs to run before\nthe listener that handles it. Depending on the extension that handles it and\nusing the `COMMAND_PRIORITY_BEFORE_*` variant of its priority does that\nwithout escalating to a higher priority. See\n[Priorities and ordering](#priorities-and-ordering) below.\n\nIn a legacy React plugin, return the `registerCommand` call from a\n`useEffect` instead.\n\nAnd as seen above and below, `registerCommand`'s callback can return `true` to signal to the other listeners that the command has been handled and propagation will be stopped.\n\nHere's a simplified example of handling a `KEY_TAB_COMMAND` from [`TabIndentationExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-extension/src/TabIndentationExtension.ts), which is used to dispatch a `OUTDENT_CONTENT_COMMAND` or `INDENT_CONTENT_COMMAND`.\n\n```js\neditor.registerCommand(\n KEY_TAB_COMMAND,\n (payload) => {\n const event: KeyboardEvent = payload;\n event.preventDefault();\n return editor.dispatchCommand(\n event.shiftKey ? OUTDENT_CONTENT_COMMAND : INDENT_CONTENT_COMMAND,\n );\n },\n COMMAND_PRIORITY_EDITOR,\n);\n```\n\nNote that the same `KEY_TAB_COMMAND` command is registered by [`LexicalTableSelectionHelpers.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical-table/src/LexicalTableSelectionHelpers.ts), which handles moving focus to the next or previous cell within a `TableNode`, but the priority is high (`COMMAND_PRIORITY_HIGH`) because this behavior is very important.\n\n### Priorities and ordering\n\nCommand listeners are called in the following order until a listener returns `true`:\n\n- From priority highest to lowest (critical, high, normal, low, editor)\n- All `COMMAND_PRIORITY_BEFORE_${priority}` listeners, most recently registered first\n- All `COMMAND_PRIORITY_${priority}` listeners, in registration order\n\n:::note\n\nThe `COMMAND_PRIORITY_BEFORE_*` priorities make it much easier to override\ndefault behavior without escalating the priority.\n\n:::\n\nIt is best practice to use the lowest priority possible, so most commands will\nbe registered with `COMMAND_PRIORITY_EDITOR` for the default behavior, then\ncommands to override that behavior can be registered with\n`COMMAND_PRIORITY_BEFORE_EDITOR`. The higher priorities mostly serve purposes\nsuch as being able to observe-but-not-handle events and to support legacy code\nthat predates the availability of `COMMAND_PRIORITY_BEFORE_*`.\n\nA modern lexical app will typically only need the\n`COMMAND_PRIORITY_BEFORE_EDITOR` priority since the\nlast-registered-called-first ordering is suitable for almost all use cases. The\nolder priorities without BEFORE can be considered legacy and are primarily\noffered for compatibility.\n\nHere is the full ordering of priorities, from lowest to highest:\n\n- `COMMAND_PRIORITY_EDITOR`\n- `COMMAND_PRIORITY_BEFORE_EDITOR`\n- `COMMAND_PRIORITY_LOW`\n- `COMMAND_PRIORITY_BEFORE_LOW`\n- `COMMAND_PRIORITY_NORMAL`\n- `COMMAND_PRIORITY_BEFORE_NORMAL`\n- `COMMAND_PRIORITY_HIGH`\n- `COMMAND_PRIORITY_BEFORE_HIGH`\n- `COMMAND_PRIORITY_CRITICAL`\n- `COMMAND_PRIORITY_BEFORE_CRITICAL`\n","isInternal":false,"tokens":1849,"sizeBytes":8664},{"name":"compared-with-prosemirror.md","path":"packages/lexical-website/docs/concepts/compared-with-prosemirror.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/compared-with-prosemirror.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Compared with ProseMirror\n\nLexical and [ProseMirror](https://prosemirror.net) are both frameworks for\nbuilding rich text editors on top of `contentEditable`, and both keep an\nimmutable document model as the source of truth. This page collects the main\ndifferences in one place, for readers who know one and are learning the other.\n\n## Document model {#document-model}\n\nLexical's tree is shaped like the HTML it renders (see\n[Document Model](./document-model.md)). This is a deliberate difference from\nProseMirror. ProseMirror's document is also a tree,\nand blocks can contain other blocks, but the inline content of a textblock is\na flat sequence of nodes (text and inline nodes) with marks for formatting and\nlinks, and every position in the document is a single integer.\n\n| | Lexical | ProseMirror |\n| -- | -- | -- |\n| Document | Immutable tree of nodes, one `RootNode` | Immutable tree of nodes, one `doc` node |\n| Node identity and navigation | Each node has a runtime key and knows its parent and siblings | Nodes are plain values with no parent links; a resolved position supplies ancestor context |\n| Blocks | `ElementNode` subclasses (paragraph, heading, list, table, …), or a block `DecoratorNode` (image, embed, …) | Block nodes defined in the schema |\n| Inline formatting | Format flags on each `TextNode` (bold, italic, code, …) | Marks on text |\n| Links and other inline wrappers | Inline `ElementNode`s (`LinkNode`, `MarkNode`) that contain text nodes | Marks on text, like formatting |\n| Embedded content | `DecoratorNode`, inline or block, rendered by your framework (for example React) | Leaf or atom nodes, often with a custom `NodeView` |\n| Several editable regions in one node | [Named slots](./named-slots.md): regions addressed by name, like a card's `title`, each isolated so editing and selection never cross the boundary | Child nodes in the order the schema's content expression allows, optionally marked `isolating`, or a separate editor inside a `NodeView` |\n| Addressing a position | Node key plus offset (`{key, offset, type}`) | One integer counted across the whole document |\n| Allowed structure | Declared by node classes, enforced with node transforms and normalization | Declared by a schema of content expressions |\n| Applying edits | Call node and selection methods inside `editor.update()` | Build a transaction from steps that address positions or ranges |\n| Rendering | Each node's `createDOM()`/`updateDOM()`, applied by the reconciler, and optionally changed per node class by a `DOMRenderExtension` override | `toDOM` in the schema, or a `NodeView` |\n\n## Serialization {#serialization}\n\nBecause a Lexical link is an element that already contains its text, it\nexports as an `` around those text nodes. A mark-based model has to find the\nadjacent text that shares a mark and group it into one element first.\n\n| Format | Lexical | ProseMirror |\n| -- | -- | -- |\n| JSON | `editorState.toJSON()`, restored with `editor.parseEditorState()` | `doc.toJSON()` and `Node.fromJSON(schema, json)` |\n| HTML export | `$generateHtmlFromNodes()`, using each node's `createDOM()` or `exportDOM()` | `DOMSerializer.fromSchema(schema)`, using `toDOM` from the schema's nodes and marks |\n| HTML import | `$generateNodesFromDOM()`, using `importDOM()` or `DOMImportExtension` rules | `DOMParser.fromSchema(schema)`, using the schema's `parseDOM` rules |\n| Markdown | `@lexical/markdown` transformers or `@lexical/mdast` | `prosemirror-markdown`: a markdown-it parser and a serializer with a function per node and mark |\n| Clipboard | Copy writes plain text, HTML, and Lexical JSON. Paste prefers the JSON, then HTML, then plain text. | Copy writes HTML and plain text. Paste parses the HTML with the schema's parse rules. |\n\nIn the JSON, a Lexical link is a `link` node with its text nodes as\n`children`, and bold is a `format` value on a `text` node, where\nProseMirror's JSON gives each text node a list of `marks`. In both editors the\ndefault HTML export reuses the definition that renders the editor\n(`createDOM()` in Lexical, `toDOM` in ProseMirror), so the two stay in step\nunless you override one. See [Serialization](../serialization/serialization.md)\nfor the details of each Lexical format.\n\n## History {#history}\n\nBoth editors group consecutive edits into one undo step. Lexical's\n[`HistoryExtension`](./history.md) merges edits made within `delay`\n(300ms by default) and keeps an unlimited stack unless you set `maxDepth`.\nProseMirror's history plugin uses `newGroupDelay: 500` and `depth: 100` by\ndefault, so `configExtension(HistoryExtension, {delay: 500, maxDepth: 100})`\nmatches its behavior.\n","isInternal":false,"tokens":1091,"sizeBytes":4640},{"name":"document-model.md","path":"packages/lexical-website/docs/concepts/document-model.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/document-model.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Document Model\n\nAn [editor state](./editor-state.md) holds a tree of nodes. This page explains\nhow that tree is shaped.\n\n## A DOM-like tree\n\nLexical's node tree is shaped like the HTML it renders. A paragraph is an\n`ElementNode` whose children are the nodes inside it, and inline structure\nnests the same way: a link is a `LinkNode` element that contains the text\nnodes it wraps, just as an `` contains its text. Each node type decides how\nit renders with `createDOM()` and `updateDOM()`, so the model maps closely to\nthe DOM, and a position in the document is a node plus an offset within it.\n\nHere is a small document with a heading, a paragraph containing bold text and\na link, a block image, and a card that has a named `title` slot as well as\nordinary body children:\n\n```mermaid\nflowchart TB\n accTitle: The shape of a Lexical document tree\n accDescr: The root has four children in order: a heading, a paragraph, an image, and a card. The heading contains the text \"Welcome\". The paragraph contains the text \"Read the \", a bold text node \"docs\", and a link, which contains the text \"here\". The image is a block decorator node with no children. The card has a named slot called title, which holds a paragraph containing the text \"Card title\", and one ordinary child, a paragraph containing the text \"Card body\".\n root[\"Root\"] --> heading[\"Heading (h1)\"]\n root --> paragraph[\"Paragraph\"]\n root --> image[\"Image
(block DecoratorNode)\"]\n root --> card[\"Card
(ElementNode)\"]\n heading --> welcome[\"Text: 'Welcome'\"]\n paragraph --> read[\"Text: 'Read the '\"]\n paragraph --> docs[\"Text: 'docs'
{ format: bold }\"]\n paragraph --> link[\"Link\"]\n link --> here[\"Text: 'here'\"]\n card -.->|\"slot: title\"| titlePara[\"Paragraph\"]\n titlePara --> titleText[\"Text: 'Card title'\"]\n card --> body[\"Paragraph\"]\n body --> bodyText[\"Text: 'Card body'\"]\n```\n\nSolid arrows are ordinary children, which form an ordered list under their\nparent and are read with `getChildren()`. The dashed arrow is a\n[named slot](./named-slots.md): a separate channel on the host, keyed by name\ninstead of position and read with `$getSlot(card, 'title')`. A slot's value\nis the root of its own isolated region, so its `getParent()` is `null` and\n`$getSlotHost()` leads back to the card. Any `ElementNode` or `DecoratorNode`\ncan host slots, so a decorator such as the image could also expose an\neditable caption this way.\n\n## Working with the tree\n\nLexical code navigates the document the way DOM code does, with methods like\n`getParent()`, `getChildren()`, and `getNextSibling()`, and each node owns the\nDOM it renders. The resemblance is structural, not one\nnode per HTML element: bold or italic text, for example, is a format on a\n`TextNode`, not a separate `` or `` node. See\n[Nodes](./nodes.mdx) for the built-in node types.\n\n## Customizing rendering\n\nYou can also change how nodes render without subclassing them.\n[`DOMRenderExtension`](../serialization/dom-render.md) from `@lexical/html`\ntakes overrides for `createDOM`, `updateDOM`, and `exportDOM`, for one node\nclass or for every node, such as adding a `data-` attribute or wrapping a\nnode's children in another element. Each override calls `$next()` to get the\ndefault result and adjusts it, so overrides from several extensions compose.\nExport overrides only affect HTML export, and `createDOM` overrides also carry\nthrough to export for nodes that use the default `exportDOM`. Changes made\nwhile updating the editor's DOM don't; see\n[Lexical -> HTML](../serialization/serialization.md#lexical---html) for which\nhooks reach export.\n\nFor how the tree is converted to and from JSON, HTML, and Markdown, see\n[Serialization](../serialization/serialization.md#formats-at-a-glance). For\nhow this model differs from a mark-based editor, see\n[Compared with ProseMirror](./compared-with-prosemirror.md).\n","isInternal":false,"tokens":949,"sizeBytes":3859},{"name":"dom-events.md","path":"packages/lexical-website/docs/concepts/dom-events.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/dom-events.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"\n\n# Working with DOM Events\n\nSometimes, when working with Lexical, it might be necessary or useful for you to attach a DOM Event Listener to the underlying DOM nodes that Lexical controls. For instance, you might want to show a popover when a user mouses over a specific node or open a modal when they click on a node. Either of these use cases (and many others) can be accomplished via native DOM Event Listeners. There are 3 main ways that you can listen for DOM Events on nodes controlled by Lexical:\n\n## 1. Event Delegation\n\nOne way to handle events inside the editor is to set a listener on the editor root element (the contentEditable Lexical attaches to). You can do this using a [Root Listener](listeners.md).\n\n```js\nfunction myListener(event) {\n // You may want to filter on the event target here\n // to only include clicks on certain types of DOM Nodes.\n alert('Nice!');\n}\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) => {\n if (rootElement === null) {\n return;\n }\n // add the listener to the current root element\n rootElement.addEventListener('click', myListener);\n // remove the listener when the root element changes - make sure the ref\n // to myListener is stable so the removal works and you avoid a memory leak.\n return () => rootElement.removeEventListener('click', myListener);\n }),\n});\n```\n\nAn extension's `register` returns a cleanup function, and the editor calls it\nwhen it is disposed, so there is no teardown to write by hand. Add\n`ClickExtension` to your editor's `dependencies` to use it.\nThis can be a simple, efficient way to handle some use cases, since it's not necessary to attach a listener to each DOM node individually.\n\nThe `addEventListener`/`removeEventListener` pairing above is common enough that the core `lexical` package exports a `registerEventListener(target, type, listener, options?)` helper. It attaches the listener and returns a dispose function that removes it, so the example above becomes:\n\n```js\nimport {defineExtension, registerEventListener} from 'lexical';\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) =>\n // registerEventListener returns the matching removeEventListener cleanup,\n // so there's no need to write the teardown by hand.\n rootElement === null\n ? undefined\n : registerEventListener(rootElement, 'click', myListener),\n ),\n});\n```\n\nIt mirrors the `addEventListener` overloads (so the event type is strongly typed) and composes well with `mergeRegister` when you need to register several listeners at once.\n\nTo attach several listeners to the same target, `registerEventListeners(target, listeners, options?)` takes a `{type: listener}` map and returns a single dispose function that removes all of them. Each listener's event argument is still strongly typed per event type, and the optional `options` argument is shared across every listener:\n\n```js\nimport {registerEventListeners} from 'lexical';\n\nconst removeListeners = registerEventListeners(\n rootElement,\n {\n click: onClick,\n keydown: onKeyDown, // receives a KeyboardEvent\n },\n {capture: true}, // shared by both listeners\n);\n```\n\nBecause `options` is shared, register a group that needs different options (such as a different `capture` flag) with a separate `registerEventListeners` call and combine the results with `mergeRegister`.\n\n## 2. Directly Attach Handlers\n\nIn some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that your handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](listeners.md).\n\n```js\nconst registeredElements: WeakSet = new WeakSet();\nconst removeMutationListener = editor.registerMutationListener(nodeType, (mutations) => {\n editor.getEditorState().read(() => {\n for (const [key, mutation] of mutations) {\n const element: null | HTMLElement = editor.getElementByKey(key);\n if (\n // Updated might be a move, so that might mean a new DOM element\n // is created. In this case, we need to add an event listener too.\n (mutation === 'created' || mutation === 'updated') &&\n element !== null &&\n !registeredElements.has(element)\n ) {\n registeredElements.add(element);\n element.addEventListener('click', (event: Event) => {\n alert('Nice!');\n });\n }\n }\n });\n});\n\n// teardown the listener - return it from an extension's `register` so the\n// editor removes it when it is disposed.\nremoveMutationListener();\n```\nNotice that here we don't worry about cleaning up, as Lexical will dereference the underlying DOM nodes and allow the JavaScript runtime garbage collector to clean up their listeners.\n\n## 3. Use NodeEventPlugin\n\nIf you're using React, we've wrapped approach #2 up into a simple React plugin that you can render inside your composer to achieve the same effect, without worrying about the details:\n\n```jsx\n\n {\n alert('Nice!');\n }}\n />\n\n```\n\nIf the editor lives inside a shadow root or an iframe, see\n[Shadow DOM and iframes](./shadow-dom.md) for the helper to read\n`event.target` through the shadow boundary — the browser retargets it to the\nshadow host on listeners attached above the boundary, so a plain\n`event.target` won't match a node inside the editor.\n","isInternal":false,"tokens":1266,"sizeBytes":5987},{"name":"editor-state.md","path":"packages/lexical-website/docs/concepts/editor-state.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/editor-state.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"\n\n# Editor State\n\n## Why is it necessary?\n\nWith Lexical, the source of truth is not the DOM, but rather an underlying state model\nthat Lexical maintains and associates with an editor instance.\n\nWhile HTML is great for storing rich text content it's often \"way too flexible\" when it comes to text editing.\nFor example the following lines of content will produce equal outcome:\n\n```html\nLexical\nLexical\nLexical\n```\n\n
\n See rendered version!\n
\n Lexical\n Lexical\n Lexical\n
\n
\n\nOf course, there are ways to normalize all these variants to a single canonical form, however this would require DOM manipulation and so re-rendering of the content. And to overcome this we can use Virtual DOM, or State.\n\nOn top of that it allows to decouple content structure from content formatting. Let's look at this example stored in HTML:\n\n```html\n

Why did the JavaScript developer go to the bar? Because he couldn't handle his Promises

\n```\n\n
\n \"Nested\n
Nested structure of the HTML state because of the formatting
\n
\n\nIn contrast, Lexical decouples structure from formatting by offsetting this information to attributes. This allows us to have canonical document structure regardless of the order in which different styles were applied.\n\nHere is the same content as a Lexical node tree, printed the way the\n[tree view](/docs/getting-started/devtools) shows it (the numbers are node keys):\n\n```text\nroot\n └ (2) paragraph\n ├ (3) text \"Why did the JavaScript developer go to the bar? \"\n ├ (4) text \"Because he couldn't handle his \" { format: bold }\n ├ (5) text \"Promise\" { format: bold, italic }\n └ (6) text \"s\" { format: bold }\n```\n\nThe paragraph's children are a flat list of text nodes, and the formatting is a\nproperty of each one, so there is only one way to represent this content.\n\n## Understanding the Editor State\n\nYou can get the latest editor state from an editor by calling `editor.getEditorState()`.\n\nEditor states have two phases:\n\n- During an update they can be thought of as \"mutable\". See \"Updating state\" below to\n mutate an editor state.\n- After an update, the editor state is then locked and deemed immutable from there on. This\n editor state can therefore be thought of as a \"snapshot\".\n\nEditor states contain two core things:\n\n- The editor node tree (starting from the root node). See\n [Document Model](./document-model.md) for how the tree is shaped.\n- The editor [selection](./selection.md) (which can be null).\n\nFor example, \"Hello world\" with a link around \"world\" and the caret at the\nend looks like this:\n\n```mermaid\nflowchart TB\n accTitle: A simple editor state\n accDescr: The root contains a paragraph with a \"Hello \" text node and a link. The link contains the \"world\" text node. The selection's anchor and focus both point to offset 5 in \"world\".\n subgraph state[\"EditorState\"]\n direction TB\n root[\"Root\"] --> paragraph[\"Paragraph\"]\n paragraph --> hello[\"Text: 'Hello '\"]\n paragraph --> link[\"Link\"]\n link --> world[\"Text: 'world'\"]\n selection[\"Selection\"] -.->|\"caret at offset 5\"| world\n end\n```\n\n`editor.getEditorState()` returns the latest committed state. Its `toJSON()`\nmethod serializes the document tree only; the selection and the runtime node\nkeys are not included. To restore saved content, pass the JSON to\n`editor.parseEditorState()` and the result to `editor.setEditorState()`. The\neditor must have the same node types registered. See\n[Serialization](../serialization/serialization.md) for JSON, HTML, and\nMarkdown.\n\nHere's an example of how you can initialize an editor with saved content and\nthen persist it. The saved JSON is passed as the editor's `$initialEditorState`:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\n// Get the saved content (e.g. loaded from a backend)\nconst initialEditorState = await loadContent();\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n);\neditor.setRootElement(document.getElementById('editor'));\n\n// Store the content (e.g. when the user submits a form)\nasync function onSubmit() {\n await saveContent(JSON.stringify(editor.getEditorState()));\n}\n```\n\nWith React, pass the extension to `LexicalExtensionComposer`. A component\nrendered inside it can reach the editor with `useLexicalComposerContext()`:\n\n```jsx\nimport {LexicalExtensionComposer} from '@lexical/react/LexicalExtensionComposer';\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\nimport {useMemo} from 'react';\n\nfunction SaveButton() {\n const [editor] = useLexicalComposerContext();\n return (\n saveContent(JSON.stringify(editor.getEditorState()))}>\n Save\n \n );\n}\n\nfunction Editor({initialEditorState}) {\n // The editor is recreated whenever this extension changes,\n // so keep it stable for the life of the editor.\n const extension = useMemo(\n () =>\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n [initialEditorState],\n );\n return (\n \n \n \n );\n}\n```\n\n`$initialEditorState` is applied once, when the editor is built; changing it\nlater has no effect on that editor. See \"Updating state\" below for the proper\nway to change editor state after initialization.\n\n`$initialEditorState` accepts:\n\n- a JSON string or a parsed `SerializedEditorState` object, passed to\n `editor.parseEditorState()` (as in the example above);\n- an `EditorState` instance, applied directly with `editor.setEditorState()`;\n- a function `(editor) => void`, run inside `editor.update(...)`;\n- `null`, which skips default initialization entirely. Use this with\n [collaboration](/docs/collaboration/react) so that the Yjs document, not\n Lexical, owns the initial state.\n\nOmitting the field (or passing `undefined`) seeds the root with a default empty\n`ParagraphNode`. The two are not interchangeable: `null` leaves the root with no children,\nwhile `undefined` produces a single empty line. If your `loadContent` may yield `null` or\n`undefined` for new documents, coalesce to `undefined` (e.g. `(await loadContent()) ?? undefined`)\nso the editor still gets the default paragraph rather than the collab-style uninitialized\nstate.\n\nThe legacy `LexicalComposer` takes the same values as `initialConfig.editorState`,\nexcept that a function there only runs if the root is still empty.\n\n## Updating state\n\nAll reads and writes of the document happen inside a synchronous callback:\n\n```js\nimport {$createParagraphNode, $createTextNode, $getRoot} from 'lexical';\n\neditor.update(() => {\n const paragraph = $createParagraphNode();\n paragraph.append($createTextNode('Hello world'));\n $getRoot().append(paragraph);\n});\n\nconst text = editor.read('force-commit', () => $getRoot().getTextContent());\n```\n\n### The `$` function convention {#dollar-functions}\n\nFunctions whose names start with `$`, such as `$getRoot()` and\n`$getSelection()`, only work inside one of these callbacks, because they act\non the active editor state. Calling them anywhere else throws an error. The\nconvention is similar to React Hooks:\n\n| | React Hooks | Lexical `$` functions |\n| -- | -- | -- |\n| Naming | `useFunction` | `$function` |\n| Can only be called | while rendering a component | inside an update or read |\n| Can call others of the same kind | ✅ | ✅ |\n| Must be synchronous | ✅ | ✅ |\n| Must be called unconditionally, in the same order | ✅ | ❌ No such rule |\n\nCommand handlers and node transforms already run inside an update, so they\ncan call `$` functions directly.\n\nThis works because, while a callback runs, Lexical keeps the active editor and\nthe active editor state in module-level variables, and `$` functions read\nthem: `$getRoot()` returns the root of the active state, and `$getEditor()`\nreturns the active editor. Because the callback is synchronous, nothing else\ncan run in between and change them. The same mechanism enforces the\ndifference between reads and updates. Inside a read, a method that would\nchange a node throws `Cannot use method in read-only mode.`\n\nGive your own functions a `$` prefix when they call `$` functions, so it is\nclear where they can be used. The\n[`@lexical/rules-of-lexical`](/docs/packages/lexical-eslint-plugin) ESLint rule\nchecks this convention.\n\nThe same rule applies to node objects. Call node methods only inside a read or\nupdate. Every node has a key that identifies it across versions of the editor\nstate, and node methods use that key to find the latest version of the node.\nThis is why a node reference taken earlier in an update stays usable after the\nnode changes. Keys exist only at runtime: they are not serialized, and you\nshould treat them as opaque.\n\nBecause the callbacks are synchronous, do any asynchronous work (fetching\ndata, awaiting a promise) first, and then enter an update with the result.\n\nAvoid nesting one `editor.update()` inside another: the inner update does not\nrun immediately but is queued to run after the outer one. Never start an\nupdate inside a read.\n\nEach update works on a pending copy of the editor state, and updates made in\nthe same tick are committed and reconciled to the DOM together. See\n[Updates](./updates.mdx#update-lifecycle) for the full lifecycle.\n\n### Replacing the state\n\nAnother way to set state is `setEditorState` method, which replaces current state with the one passed as an argument.\n\nHere's an example of how you can set editor state from a stringified JSON:\n\n```js\nconst editorState = editor.parseEditorState(editorStateJSONString);\neditor.setEditorState(editorState);\n```\n\n:::warning\n\n`setEditorState` rejects an `EditorState` that satisfies `editorState.isEmpty()` — i.e.\nthe root is the only node and there is no selection. In a development build it throws\n`\"setEditorState: the editor state is empty. Ensure the editor state's root node never\nbecomes empty.\"`; in production it warns with the same message and recovers by appending\nan empty `ParagraphNode`, so the editor stays usable. The `EditorState` produced by\ninitializing with `editorState: null` and never appending content (typical for a\ncollaboration document before peers connect) has exactly this shape, so persisting and\nreloading such a state hits this path. Note that `parseEditorState` itself succeeds — the\ncheck lands on the apply step. To avoid relying on the recovery, guard with\n`editorState.isEmpty()` before calling `setEditorState`, or seed the document with a\n`ParagraphNode` before serializing.\n\n:::\n\n## Reading state\n\nWhich state you see depends on how you read it:\n\n- Inside `editor.update()` you see the **pending** state, where your changes\n are visible but transforms and reconciliation may not have run yet.\n `editor.read('pending', fn)` gives you the same view without allowing\n changes.\n- `editor.read('force-commit', fn)` first commits any pending updates, so it\n always sees a consistent, reconciled state. Do not call it inside an update.\n `editor.read(fn)` with no mode does the same thing, and is kept for\n convenience and backwards compatibility. Inside a mutation or update\n listener it does not commit an update that another listener started (that\n update commits after the listeners have run, so they observe commits in\n order); use `editor.read('latest', fn)` there.\n- `editor.read('latest', fn)` reads the most recently reconciled state without\n committing anything, so pending changes are not visible.\n- `editorState.read(fn, {editor})` reads one particular snapshot, such as the\n `editorState` an update listener receives. Passing the `editor` keeps\n `$getEditor()` and extension lookups working inside the callback.\n\n## State update listener\n\nIf you want to know when the editor updates so you can react to the changes, you can add an update\nlistener to the editor, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(\n () => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n },\n // Passing the editor keeps $getEditor() and extension lookups working.\n {editor},\n );\n});\n```\n\n## When are Listeners, Transforms, and Commands called?\n\nThere are several types of callbacks that can be registered with the editor that are related to\nupdates of the Editor State.\n\n| Callback Type | When It's Called |\n| -- | -- |\n| Update Listener | After reconciliation |\n| Mutation Listener | After reconciliation |\n| Node Transform | During `editor.update()`, after the callback finishes, if any instances of the node type they are registered for were updated |\n| Command | As soon as the command is dispatched to the editor (called from an implicit `editor.update()`) |\n\n## Synchronous reconciliation with discrete updates\n\nWhile commit scheduling and batching are normally what we want, they can sometimes get in the way.\n\nConsider this example: you're trying to manipulate an editor state in a server context and then persist it in a database.\n\n```js\neditor.update(() => {\n // manipulate the state...\n});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\nThis code will not work as expected, because the `saveToDatabase` call will happen before the state has been committed.\nThe state that will be saved will be the same one that existed before the update.\n\nFortunately, the `discrete` option for `LexicalEditor.update` forces an update to be immediately committed.\n\n```js\neditor.update(() => {\n // manipulate the state...\n}, {discrete: true});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\n### Cloning state\n\nLexical state can be cloned, optionally with custom selection. One of the scenarios where you'd want to do it\nis setting editor's state but not forcing any selection:\n\n```js\n// Passing `null` as a selection value to prevent focusing the editor\neditor.setEditorState(editorState.clone(null));\n```\n","isInternal":false,"tokens":3370,"sizeBytes":14692},{"name":"headless.md","path":"packages/lexical-website/docs/concepts/headless.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/headless.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Running Without a Browser\n\nThe DOM is only needed to show an editor on screen. Because every read and\nupdate goes through the editor state, Lexical also works where there is no\nbrowser DOM:\n\n- **With no DOM at all.** An editor that has no root element skips\n reconciliation and DOM selection entirely, so you can build one with\n `buildEditorFromExtensions()` and never call `setRootElement()`. Adding\n `HeadlessExtension` from `@lexical/headless` makes that explicit: attaching a\n root element then throws, and nested editors are headless too. Updates,\n transforms, listeners, commands, and JSON serialization all still work,\n which is enough to process documents on a server, apply changes from a\n collaboration backend, or write tests.\n- **With a virtual DOM** such as happy-dom or jsdom, for the features that\n create DOM nodes, like HTML import and export. `withDOM()` from\n `@lexical/headless/dom` runs a callback with a temporary happy-dom window,\n for example to convert HTML on a server.\n\n## Example: converting saved JSON to HTML on a server\n\n```ts\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {HeadlessExtension} from '@lexical/headless';\nimport {withDOM} from '@lexical/headless/dom';\nimport {$generateHtmlFromNodes} from '@lexical/html';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [HeadlessExtension, RichTextExtension],\n name: '@my-app/server-editor',\n }),\n);\n\nexport function jsonToHtml(json: string): string {\n editor.setEditorState(editor.parseEditorState(json));\n return withDOM(() => editor.read(() => $generateHtmlFromNodes(editor)));\n}\n```\n\nThe editor must have the same node types registered as the editor that saved\nthe JSON, which is why it uses the same extensions. JSON and Markdown\nconversion do not need `withDOM()`.\n\n## `createHeadlessEditor()`\n\nBefore extensions, headless editors were created with `createHeadlessEditor()`\nfrom `@lexical/headless`. It still works, and it makes DOM-only methods such as\n`registerRootListener` and `registerMutationListener` throw. Because many\nextensions register those listeners, use `HeadlessExtension` with\n`buildEditorFromExtensions()` in new code.\n","isInternal":false,"tokens":517,"sizeBytes":2291},{"name":"history.md","path":"packages/lexical-website/docs/concepts/history.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/history.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# History\n\nLexical adds support for Undo and Redo through the `@lexical/history` package —\n`registerHistory`, the `HistoryExtension` extension, or the `HistoryPlugin`\nReact component from `@lexical/react/LexicalHistoryPlugin`. Part of undo and redo requires supporting coalescing of certain dynamic operations such as continuous typing. The below provides background information regarding the continuous typing undo coalescing feature.\n\n**Undo Coalescing of Typed Text**\n\n**TL;DR**\nWhen working with text editors, users expect a well polished undo experience. A key part of this is a smooth, well thought out workflow when undoing continuous typing events. For this post, strict typing events may be limited to typing characters, backspacing and forward deleting. Users generally expect that continuous typing should fully undo with a single undo gesture and that they don’t require separate undo gestures for each character.\nThe algorithm that covers this is “undo coalescing of typed text” and there’s a certain degree of nuance involved. This post covers that nuance while attempting to avoid prescriptive implementation details.\n\n**What Kind of Edits Require Coalescing?**\nAs mentioned above, continuous typing should be coalesced into a single undo action. Continuous typing is a loaded phrase and we’ll get into some details below.\nThere are other types of edits that require undo coalescing such as rapidly resizing an image or rapidly changing the font size of selected text. These latter two examples fall under what might be termed “dynamic operations” and their implementation might vary quite a bit from coalescing of typing.\n\n**What Constitutes Continuous Typing?**\nFor the purposes of undo coalescing, continuous typing events are safely limited to these three actions:\n\n1. Forward typing characters (heads up, composed character typing discussed later).\n2. Deleting backwards, e.g. backspace gestures including backspace key presses.\n3. Forward deletion, e.g. forward delete gestures including Delete key presses.\n\nAny interruption to the above breaks the notion of continuous typing. Note that switching between either of these three actions may itself be considered an interruption of continuous typing or it may not. This ends up being a usability decision. In my opinion, when examining various word processors, switching between these three actions should maintain continuity, because users often make typos or corrections in the flow of typing and therefore would lean towards the whole sequence of typing, backspacing and deleting to be within a single undoable session.\nNote that Google Docs and Quip treat a switch between typing, backspacing and deleting as disruptions to the continuous typing sessions.\n\n**Start with Selected Text and Followup with Typing**\nLet’s start with some selected text. The user may have selected the text directly, as a result of pasting text or through some other sequence of steps. When followed by continuous typing, the initial selection should be included along with the following typing events as part of a single coalesced undo session.\n\n**Timeouts**\nText editing is generally a modeless user experience and so just about any event beyond the above typing actions will disrupt continuous typing. The first and foremost is a timeout.\nQuip seems to require continuous typing to occur within 1 second intervals, whereas Google Docs requires about 2 seconds. In my opinion, the timeout may stretch to as long as 3 to 5 seconds. The more time between typing events, the more chance the user has to intentionally input a block of text, a thought or concept.\nThe use of a timeout is not necessarily required, and the amount of time is certainly up for debate. Collaborative co-editing also makes use of timeouts when grouping text that is merged across clients. Longer timeouts tend to make collaboration a smoother, less disruptive experience, because receiving other client input while expressing one’s thoughts tends to be unhelpful.\nImplementers should consider the correct timeout based on their customer expectations and related collaborative features that might share this timeout.\n\n**Hard and Soft Returns**\nHard returns as generated by pressing the Return key tend to disrupt and thereby reset continuous typing.\nFor Google Docs and Quip, soft returns as generated by pressing shift+Return key do not terminate continuous typing. This makes sense in that the soft return ends text wrap but does not end the paragraph.\n\n**Changing Selections and Key Focus**\nAny change to the selection by the user should terminate coalescing. This includes:\n\n- Arrow gesture navigation.\n- Gestures to select a word, a sentence or a paragraph.\n- Any other selection change that does not move the blinking caret to the next or previous character by way of the above mentioned typing events.\n\nAdditionally, ending keyboard focus on the editing window, including moving focus to another editing window or a different view within the same window should also terminate coalescing. This also includes setting focus to modal popovers, such as, for example, a hyperlink property editor.\n\n**Composed Characters**\nCharacter composition occurs when typing diacritics, CJK and even emojis. The process usually involves at least these three phases:\n\n- Start composition.\n- Replace composed text with other text and remain composing. This step may occur many times within a single composition session.\n- Stop composition either through accepting the text or canceling the latest input.\n\nCoalescing should terminate at start composition. Replacing composed text should generally be coalesced. Stopping composition may or may not reset coalescing depending upon the implementation. Quip appears to try to coalesce multiple composed characters, but disrupts coalescing when switching between composed and non-composed characters. Google Docs appears to disrupt coalescing more frequently. Both coalesce the text replacements.\n\n**Auto Correct, Spelling Corrections and Text Substitutions**\nText substitution behaves much like composed characters. When the text is transformed, the coalescing should terminate and the transformed text becomes the first coalesced entry in the next undo session.\n\n**Copy & Pasting**\nAny actions like copy and paste typically trigger events that are not part of the 3 continuous typing actions described above. So, copy and paste also terminates coalescing.\n\n**In Conclusion**\nText undo coalescing greatly improves the usability of undo in that it allows the user to bypass all the intermediate events that went into forming or re-forming text within a paragraph. Given the modeless nature of text editing, limiting continuous typing to strictly three events allows for a robust and clean implementation. Implementers will need tight bottlenecks to trap selection changes, key focus changes as well as changes from collaborative clients. While the above is not complete by any means, I hope readers will find it helpful.\n\n## Tuning HistoryExtension for memory and long sessions\n\n`HistoryExtension` ships with config values chosen for the common case\nof a short-lived editor on a richly interactive surface. For\napplications that keep an editor mounted for a long time — chat\nthreads, long documents, anything where the user may produce thousands\nof distinct history events without reloading the page — two settings\nare worth tuning explicitly.\n\n### `maxDepth` — cap the undo stack\n\nBy default `maxDepth` is `null`, meaning the undo stack is\n**unbounded**. Every separate-history boundary (see \"What Constitutes\nContinuous Typing?\" above) pushes a `HistoryStateEntry` that retains a\nfull `EditorState` snapshot. Snapshots share a copy-on-write\n`NodeMap`, so the marginal cost of any one entry is small, but it is\nnot zero — and an unbounded stack accumulates a long tail over time.\n\nSet a finite `maxDepth` to keep the stack at a fixed length. The\nextension FIFO-evicts the oldest entries past the cap; older snapshots\nbecome unreachable and can be collected.\n\n```ts\nimport {configExtension, defineExtension} from 'lexical';\nimport {HistoryExtension} from '@lexical/history';\n\nconst editorExtension = defineExtension({\n // ...\n dependencies: [\n // 100 events is a reasonable starting point that supports a deep\n // enough undo stack for almost any interactive editing session.\n configExtension(HistoryExtension, {maxDepth: 100}),\n ],\n});\n```\n\nThe cap is also exposed as a writable signal on\n`HistoryExtension.output.maxDepth`, so it can be reconfigured at\nruntime (the new value applies to future pushes — the current stack\nis not retroactively trimmed when the cap is lowered).\n\n### `delay` — coalesce more aggressively\n\n`delay` is the merge window during which adjacent edits collapse into\nthe current history entry instead of pushing a new one. The default is\n`300`ms. A longer delay means fewer history events for the same\ntyping burst, which:\n\n- reduces the rate at which `undoStack` grows, multiplying the effect\n of any `maxDepth` cap, and\n- gives the user undo gestures that match larger semantic chunks of\n their writing.\n\nFor text-heavy editors a value in the `500`–`1000`ms range is common.\n\n```ts\nconfigExtension(HistoryExtension, {delay: 500, maxDepth: 100}),\n```\n\n### When NOT to cap history\n\nIf your editor is short-lived (mounted only for the duration of a\nmodal, page form, or single message draft) and undo is expected to\nreach back to the document's initial state, the default `maxDepth:\nnull` is fine — the stack will be discarded with the editor instance.\nThe cap matters when an editor is **long-lived** and can accumulate\nthousands of distinct history events without unmounting.\n","isInternal":false,"tokens":1944,"sizeBytes":9707},{"name":"key-management.md","path":"packages/lexical-website/docs/concepts/key-management.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/key-management.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Key Management\n\nKeys are a fundamental concept in Lexical that enable efficient state management and node tracking. Understanding how keys work is crucial for building reliable editor implementations.\n\n## What are Keys?\n\nThe `__key` property is a unique identifier assigned to each node in the Lexical editor. These keys are:\n- Automatically generated by Lexical\n- Used to track nodes in the editor state\n- Essential for state management and updates\n- Immutable during a node's lifecycle\n\n## When to Use `__key`?\n\n### ✅ Correct Usage\n\nKeys should ONLY be used in two specific situations:\n\n1. **In Node Constructors**\n```typescript\nclass MyCustomNode extends ElementNode {\n constructor(someData: string, key?: NodeKey) {\n super(key); // Correctly passing key to parent constructor\n this.__someData = someData;\n }\n}\n```\n\n2. **In Static Clone Methods**\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### ❌ Incorrect Usage\n\nNever use keys in these situations:\n\n```typescript\n// ❌ Don't pass keys between different nodes\nconst newNode = new MyCustomNode(existingNode.__key);\n\n// ❌ Don't manipulate keys directly\nnode.__key = 'custom-key';\n```\n\n## How Lexical Uses Keys\n\n### Diagram\n\nThe dotted outlines show nodes that are re-used in a zero-copy fashion from one EditorState to the next\n\n```mermaid\ngraph TB\n subgraph s0[\"Initial State\"]\n direction TB\n m0[\"NodeMap (v0)\"]\n m0 -->|Key A| n0a[\"A (v0)\"]\n m0 -->|Key B| n0b[\"B (v0)\"]\n end\n subgraph s1[\"Create Node C\"]\n direction TB\n style n1a stroke-dasharray: 5 5\n style n1b stroke-dasharray: 5 5\n m1[\"NodeMap (v1)\"]\n m1 -->|Key A| n1a[\"A (v0)\"]\n m1 -->|Key B| n1b[\"B (v0)\"]\n m1 -->|Key C| n1c[\"C (v0)\"]\n end\n subgraph s2[\"Update Node A\"]\n direction TB\n style n2a stroke-dasharray: 5 0\n style n2b stroke-dasharray: 5 5\n style n2c stroke-dasharray: 5 5\n m2[\"NodeMap (v1)\"]\n m2 -->|Key A| n2a[\"A (v1)\"]\n m2 -->|Key B| n2b[\"B (v0)\"]\n m2 -->|Key C| n2c[\"C (v0)\"]\n end\n s0 -.-> s1 -.-> s2\n```\n\n### Node Map Structure\n\nThe EditorState maintains a `Map` that tracks all nodes. Nodes refer to each other using keys in their internal pointers:\n\n```typescript\n// Internal node structure (not for direct usage)\n{\n __prev: null | NodeKey,\n __next: null | NodeKey,\n __parent: null | NodeKey,\n // __first, __last and __size are only for ElementNode to track its children\n __first: null | NodeKey,\n __last: null | NodeKey,\n __size: number\n}\n```\n\nThese internal pointers maintain the tree structure and should never be manipulated directly.\n\n### Key-Related APIs\n\n1. **Editor Methods**\n ```typescript\n // Get node by key\n const node = $getNodeByKey(key);\n\n // Get the DOM element a node key is reconciled to\n const element = editor.getElementByKey(key);\n\n // Get latest version of a node\n const latest = node.getLatest();\n \n // Get mutable version for updates\n const mutable = node.getWritable();\n ```\n\n### Key Lifecycle\n\nNodeKeys are ephemeral and have several important characteristics:\n\n1. **Serialization**\n - Keys are never serialized\n - New keys are generated when deserializing (from JSON/HTML)\n - Keys are only meaningful within their EditorState instance\n\n2. **Uniqueness**\n - Keys are unique within an EditorState\n - Current implementation uses serial numbers for debugging\n - Should be treated as random and opaque values\n - Never logically reused\n\nKeys are used internally by Lexical to:\n1. Track nodes in the editor state\n2. Manage node updates and versions\n3. Maintain referential integrity\n4. Enable efficient state updates\n\n## Common Pitfalls\n\n1. **Key Reuse**\n ```typescript\n // ❌ Never do this\n function duplicateNode(node: LexicalNode) {\n return new SameNodeType(data, node.__key);\n }\n ```\n\n2. **Manual Key Assignment**\n ```typescript\n // ❌ Never do this\n node.__key = generateCustomKey();\n ```\n\n3. **Incorrect Constructor/Clone Implementation**\n ```typescript\n // ❌ Never do this - missing key in constructor\n class MyCustomNode extends ElementNode {\n constructor(someData: string) {\n super(); // Missing key parameter\n this.__someData = someData;\n }\n }\n\n // ✅ Correct implementation\n class MyCustomNode extends ElementNode {\n __someData: string;\n\n constructor(someData: string, key?: NodeKey) {\n super(key);\n this.__someData = someData;\n }\n \n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__someData = prevNode.__someData;\n }\n }\n ```\n\n4. **Node Replacement**\n ```typescript\n // ❌ Never re-use the key when changing the node class\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(node.__key),\n withKlass: CustomNodeType\n }\n ]\n };\n\n // ✅ Correct: Use node replacement configuration\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(),\n withKlass: CustomNodeType\n }\n ]\n };\n ```\n\n For proper node replacement, see the [Node Replacement guide](node-replacement.md).\n\n## Best Practices\n\n1. **Let Lexical Handle Keys**\n ```typescript\n import {$applyNodeReplacement} from 'lexical';\n\n // Create node helper function\n export function $createMyCustomNode(data: string): MyCustomNode {\n return $applyNodeReplacement(new MyCustomNode(data));\n }\n ```\n\n## Testing Considerations\n\nWhen writing tests involving node keys:\n\n```typescript\ntest('node creation', async () => {\n await editor.update(() => {\n // ✅ Correct: Create nodes normally\n const node = new MyCustomNode(\"test\");\n \n // ✅ Correct: Keys are automatically handled\n expect(node.__key).toBeDefined();\n expect(node.__key).not.toBe('');\n });\n});\n```\n\n## Performance Impact\n\nUnderstanding key management is crucial for performance:\n\n1. Keys enable efficient node lookup (O(1))\n2. Proper key usage prevents unnecessary re-renders\n3. Lexical's key system optimizes state updates\n4. Improper key manipulation can cause performance issues\n\n## Common Questions\n\n**Q: How do I reference a node later?**\nA: Store a reference to the node. Conventionally, all node methods will use `getLatest()` or `getWritable()` which will look up the latest version of that node before reading or writing its properties, which is equivalent to using the key but is type-safe (but may cause errors if you try to use a reference to a node that no longer exists). In some situations it may be preferable to use the key directly, which is also fine.\n\n**Q: How do I ensure unique nodes?**\nA: Let Lexical handle key generation and management. Focus on node content and structure. ","isInternal":false,"tokens":1792,"sizeBytes":7121},{"name":"keyboard-accessibility.md","path":"packages/lexical-website/docs/concepts/keyboard-accessibility.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/keyboard-accessibility.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Keyboard Accessibility\n\nLexical follows the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) keyboard model. This page documents the contracts that plugin authors and host applications rely on, so a Lexical editor can sit inside a larger keyboard-accessible flow without trapping or surprising the user.\n\n## Tab key\n\nBy default, `Tab` inside the editor follows the browser's normal focus order — it moves to the next focusable element on the page. There is no keyboard trap.\n\nThe optional `TabIndentationExtension` (`@lexical/extension`) takes over `Tab` and uses it for block indent / outdent. Hosts that mount this extension opt in to that behavior. WCAG 2.1.2 (No Keyboard Trap) still applies — pressing `Escape` blurs the editor (see below), at which point `Tab` leaves the editor again.\n\n## Escape key\n\nPressing `Escape` while the editor has focus calls `editor.blur()` via the rich-text Escape command handler (registered at `COMMAND_PRIORITY_EDITOR`). The handler only blurs when the current selection is a range selection; with a `NodeSelection` (or no selection) it returns `false` and falls through without blurring. After blur, the next `Tab` advances to the page's next focusable element — so the editor is not a hard keyboard trap. (`TabIndentationExtension` consumes `Tab` only while a range selection is active, and its own source notes that taking over `Tab` is generally discouraged for keyboard accessibility, so treat WCAG 2.1.2 conformance as something to verify in your integration rather than a guarantee.)\n\nPlugin authors who want to intercept `Escape` (modal close, dropdown close, etc.) should register their handler at a higher priority and return `true` to stop the command chain. Common patterns already established in the codebase:\n\n| Priority | Caller | Purpose |\n| --- | --- | --- |\n| `HIGH` | Floating link editor | Close the floating UI, keep editor focus |\n| `HIGH` | Equation component (while editing) | Close the equation editor input |\n| `NORMAL` | Comment plugin | Cancel inline comment editing |\n| `LOW` | Image component | Escape out of caption / resize editing: drop the inner selection and restore the `NodeSelection` on the image decorator |\n| `EDITOR` | Rich text (default) | `editor.blur()` (range selection only) |\n\nHandlers that return `false` let the chain continue, so Escape can still fall through to the default blur even after a higher-priority handler runs.\n\nSome host UI binds its close handler directly to a DOM `keydown` listener rather than going through `KEY_ESCAPE_COMMAND` — the playground's `Modal` via `window.addEventListener('keydown', ...)` and its `DropDown` via a React `onKeyDown` on the menu. Those paths run alongside the table above; they do not participate in the editor's command priority chain.\n\n## React hooks and `@lexical/a11y` extensions\n\nThe keyboard helpers below ship as `@lexical/a11y` _extensions_ — the extension is the API and does all of the work (event listeners, focus management, the live region). The `@lexical/react` hooks (`useLexicalFocusManagerRef`, `useLexicalRovingTabIndexRef`, `useLexicalFocusTrapRef`, `useLexicalAriaLiveRegion`) are thin React adapters that only _communicate_ with their extension: each returns a `RefCallback` (or an `announce` function) that drives the extension's signals. Using a hook therefore **requires** its matching extension to be registered in the editor's extension tree — it is not an optional integration path. Non-React hosts (Svelte, Vue, vanilla DOM) use the extensions directly and skip the hooks.\n\n## Toolbar focus jump\n\nThe playground uses `useLexicalFocusManagerRef` (`@lexical/react/useLexicalFocusManagerRef`) to provide a documented shortcut for moving focus from the editor to the toolbar without tabbing through the page. The hook returns a `RefCallback` that registers the attached element as a focus-managed toolbar. It listens for `Alt+F10` inside the editor and moves focus into the toolbar — preferring the item that currently carries `tabindex=\"0\"` (the active roving item, when paired with `useLexicalRovingTabIndexRef`), and otherwise the first focusable item. While focus is in the toolbar, pressing `Escape` restores both focus and the editor's prior selection via `editor.focus()`. Multiple toolbars can be registered simultaneously. Requires `FocusManagerExtension` from `@lexical/a11y` in the editor's extension tree.\n\nThis matches the WAI-ARIA editor menubar pattern and the convention used by Word and CKEditor. Hosts that don't mount `useLexicalFocusManagerRef` get the default browser flow (Tab in, Tab out).\n\n## Toolbar arrow-key navigation\n\nToolbars that opt into `useLexicalRovingTabIndexRef` (`@lexical/react/useLexicalRovingTabIndexRef`) collapse to a single tab stop: arrow keys move between items inside the toolbar; `Tab` moves past the toolbar as a whole. Items keep `tabindex=\"-1\"` except the active one (`tabindex=\"0\"`). The hook returns a `RefCallback` — multiple containers can be registered simultaneously. Tracks the WAI-ARIA toolbar pattern. Requires `RovingTabIndexExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Modal focus trap\n\n`useLexicalFocusTrapRef` (`@lexical/react/useLexicalFocusTrapRef`) returns a `RefCallback` that cycles `Tab` / `Shift+Tab` inside a modal container and restores focus to the previously-focused element on deactivation. While active, the trap also installs a document-level `focusin` listener that pulls any focus landing outside the container back to the first focusable descendant (or the container itself) — so it recovers from the browser routing `Tab` out to its own chrome. Although several containers can be _registered_, only one trap should be _active_ at a time: concurrent traps install competing `focusin` listeners and fight over focus. Escape is **not** intercepted by the hook — modal owners handle the close key themselves, so the editor's Escape contract above stays predictable. Requires `FocusTrapExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Screen reader announcements\n\n`useLexicalAriaLiveRegion` (`@lexical/react/useLexicalAriaLiveRegion`) returns a stable `announce(message)` function. The hook itself mounts no DOM — like the others above, it is a thin adapter that **requires `AriaLiveRegionExtension` from `@lexical/a11y` in the editor's extension tree**. That extension owns the lifecycle of the visually-hidden region (`role=\"status\"`, `aria-atomic`, `aria-live` defaulting to `polite` — configurable via its `politeness` config): the region is created in the extension's `register` step and disposed on the editor's teardown, not on the hook's unmount. `EditorModeAnnounceExtension` (mode transitions via `registerEditableListener`) and `HistoryAnnounceExtension` (undo / redo via `UNDO_COMMAND` / `REDO_COMMAND`) announce through the same region. Both extensions accept optional message overrides for i18n.\n\n## Component ARIA quick reference\n\nWhere Lexical already applies ARIA attributes today (set in each component's `createDOM` / `updateDOM`, declaratively in the surrounding React tree, or applied imperatively via `setAttribute` on a managed or portaled element — as the typeahead menu and the live region do):\n\n| Component | role | aria-\\* attributes |\n| --- | --- | --- |\n| `ToolbarPlugin` (playground) | `toolbar` | `aria-label` |\n| `Modal` (playground) | `dialog` | `aria-modal`, `aria-labelledby` |\n| `LexicalListItemNode` (check list leaf) | `checkbox` | `aria-checked` |\n| `LexicalMenu` typeahead popup | `listbox` | `aria-label` |\n| Editor root (while typeahead is open) | — | `aria-controls`, `aria-activedescendant` |\n| `EquationNode` (playground) | `math` | `aria-label` |\n| `useLexicalAriaLiveRegion` region | `status` | `aria-live`, `aria-atomic` |\n\nCustom nodes follow the same pattern: set the attributes in `createDOM` and re-apply in `updateDOM` when the state they reflect changes. There is no central ARIA contract on `LexicalNode`; treat each subclass's `createDOM` as the source of truth.\n\n## Browser notes\n\nLexical relies on the standard DOM `Escape` contract — verified on Chrome and Safari (macOS, normal window). Safari in fullscreen intercepts `Escape` at the browser level to exit fullscreen; that is the browser's contract, not Lexical's.\n\n## What this page does not cover\n\n- Touch / mobile screen reader gestures. The hooks above share the same DOM contracts with mobile (TalkBack, VoiceOver iOS) but mobile has not been exercised in this set of changes.\n- High contrast / forced-colors theming. See the playground's `index.css` `@media (forced-colors: active)` block for a baseline.\n","isInternal":false,"tokens":1980,"sizeBytes":8645},{"name":"listeners.md","path":"packages/lexical-website/docs/concepts/listeners.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/listeners.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"\n\n# Listeners\n\nListeners are a mechanism that lets the Editor instance inform the user when a certain operation has occurred. All listeners follow a reactive pattern where you can do an operation upon something happening in the future. All listeners also return a function that easily allows for the\nlistener to be unregistered. Below are the different listeners that Lexical supports today:\n\n## `registerUpdateListener`\n\nGet notified when Lexical commits an update to the DOM.\n\n```js\nconst removeUpdateListener = editor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(() => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n });\n});\n\n// Do not forget to unregister the listener when no longer needed!\nremoveUpdateListener();\n```\n\nThe update listener callbacks receives a single argument containing the follow properties:\n\n- `editorState` the latest updated Editor State\n- `prevEditorState` the previous Editor State\n- `tags` a Set of all tags that were passed to the update\n- `dirtyElements` a Map of the NodeKeys of ElementNodes that were marked\n dirty, to a boolean that is true when the node was intentionally mutated\n- `dirtyLeaves` a Set of the NodeKeys of all dirty nodes that are not\n ElementNodes\n- `mutatedNodes` a Map of LexicalNode constructors to a\n `Map`, or null when no DOM was mutated. Only\n populated when at least one MutationListener is registered\n- `normalizedNodes` (advanced) the keys of TextNode descendants that were\n merged with a sibling by normalization\n\nOne thing to be aware of is \"waterfall\" updates. This is where you might schedule an update inside an update\nlistener, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // Read the editorState and maybe get some value.\n editorState.read(() => {\n // ...\n });\n\n // Then schedule another update.\n editor.update(() => {\n // ...\n });\n});\n```\n\nThe problem with this pattern is that it means we end up doing two DOM updates, when we likely could have\ndone it in a single DOM update. This can have an impact on performance, which is important in a text editor.\n\nA listener that re-enqueues work without a stop condition is worse than slow.\nThe editor keeps a cascade budget: once a run of updates re-enqueues more\nthan 100 times without yielding to the event loop, it discards the entire\npending update queue and warns. Bounded activity never reaches the limit —\nthe budget is reset from a macrotask, which a genuine runaway starves — but a\ntrue loop silently loses whatever else was queued.\n\nTo avoid this, we recommend looking into [Node Transforms](transforms.md), which allow you to listen to node changes and\ntransform them as part of the same given update, meaning no waterfalls!\n\n## `registerTextContentListener`\n\nGet notified when Lexical commits an update to the DOM and the text content of the editor changes from\nthe previous state of the editor. If the text content is the same between updates, no notifications to\nthe listeners will happen.\n\n```js\nconst removeTextContentListener = editor.registerTextContentListener(\n (textContent) => {\n // The latest text content of the editor!\n console.log(textContent);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveTextContentListener();\n```\n\n## `registerMutationListener`\n\nGet notified when a specific type of Lexical node has been mutated. There are three states of mutation:\n\n- `created`\n- `destroyed`\n- `updated`\n\nMutation listeners are great for tracking the lifecycle of specific types of node. They can be used to\nhandle external UI state and UI features relating to specific types of node.\n\nIf any existing nodes are in the DOM, and skipInitialization is not true, the listener\nwill be called immediately with an updateTag of 'registerMutationListener' where all\nnodes have the 'created' NodeMutation. This can be controlled with the skipInitialization option,\nwhich defaults to false.\n\n```js\nconst removeMutationListener = editor.registerMutationListener(\n MyCustomNode,\n (mutatedNodes, { updateTags, dirtyLeaves, prevEditorState }) => {\n // mutatedNodes is a Map where each key is the NodeKey, and the value is the state of mutation.\n for (let [nodeKey, mutation] of mutatedNodes) {\n console.log(nodeKey, mutation)\n }\n },\n {skipInitialization: false}\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveMutationListener();\n```\n\n## `registerEditableListener`\n\nGet notified when the editor's mode has changed. The editor's mode can be changed\nvia `editor.setEditable(boolean)`.\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (editable) => {\n // The editor's mode is passed in!\n console.log(editable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\n## `registerDecoratorListener`\n\nGet notified when the editor's decorator object changes. The decorator object contains\nall `DecoratorNode` keys -> their decorated value. This is primarily used with external\nUI frameworks.\n\n```js\nconst removeDecoratorListener = editor.registerDecoratorListener(\n (decorators) => {\n // The editor's decorators object is passed in!\n console.log(decorators);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveDecoratorListener();\n```\n\n## `registerRootListener`\n\nGet notified when the editor's root DOM element (the content editable Lexical attaches to) changes. This is primarily used to\nattach event listeners to the root element. *The root listener function is executed directly upon registration and then on any subsequent update.*\n\n```js\nconst removeRootListener = editor.registerRootListener(\n (rootElement, prevRootElement) => {\n //add listeners to the new root element\n //remove listeners from the old root element\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveRootListener();\n```\n","isInternal":false,"tokens":1320,"sizeBytes":6143},{"name":"named-slots.md","path":"packages/lexical-website/docs/concepts/named-slots.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/named-slots.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Named Slots\n\n:::warning\n\nNamed slots are experimental. The APIs described here are tagged\n`@experimental`, may change without a major version bump, and the\nserialization and collab formats should be treated as unstable until the\nfeature is stabilized.\n\n:::\n\nNamed slots let a single host node (an ElementNode or a DecoratorNode) own\nseveral isolated editable regions addressed by name — a Card's `title`, a\nPullQuote's `quote` and `attribution` — inside the host's own EditorState.\nEach region takes its own caret and formatting, never merges across the\nboundary, and `Cmd+A` doesn't spill into the rest of the document.\n\nBefore named slots, the usual answer was a nested editor per region: every\nregion lives in its own EditorState, so moving nodes between regions and\nkeeping history and collab in sync all require serialization and extra\n`editor.update` passes. The other node shapes don't fit either: plain\nElementNode children share one undivided linked list (Backspace at a region\nstart merges it into the previous region), and a DecoratorNode is atomic, so\nLexical can't own selection, collab, or serialization inside it. With named\nslots, editing a slot is just editing the one tree.\n\n:::note\n\nNamed slots are the model-level generalization of the rendering concept\nbehind [`$getDOMSlot`](/docs/api/modules/lexical#getdomslot) /\n`ElementDOMSlot` in the\n[DOM rendering](../serialization/dom-render.md) documentation. Every\nElementNode already has one _unnamed_ children channel, and `$getDOMSlot`\ncontrols where that channel's content attaches in the node's DOM. Named\nslots are additional, explicitly-named channels alongside it — symmetric in\nthat each renders into a controllable location in the host's DOM — but they\nalso carry the model-level semantics the unnamed channel doesn't: isolation\n(the virtual shadow root below), a separate NodeKey map, and their own\nserialization and collaboration.\n\n:::\n\n## The Model\n\nA host keeps a second child channel, a `Map` of slot name to NodeKey,\nseparate from its ordinary linked-list children. A slot value has its slot\nhost pointer set and `getParent() === null`, with exactly one of the two\nnon-null: `getParent()` stops at the slot boundary, and you climb out only\nthrough [`$getSlotHost()`](/docs/api/modules/lexical#getslothost).\n\nThe slot link itself acts as a **virtual invisible shadow root** between the\nhost and the value. Isolation is structural rather than a convention — an\naccidental boundary crossing surfaces as a thrown invariant, not silent\ncorruption.\n\nIn the DOM, each value renders synchronously into a keyless\n`
\">` container parked slots-first in the host\nDOM as a **hidden placeholder** (`display: none`), in a canonical order\nderived from the host class (see [slot order](#slot-order)). Nothing is\nvisible until the host explicitly attaches the container somewhere (see\n[Rendering](#rendering)) — mirroring how\n[`getDOMSlot`](/docs/api/modules/lexical#getdomslot) gives an element\ncontrol over where its linked-list children render.\n\n## Hosts and Values\n\nAny ElementNode or DecoratorNode can host slots. An ElementNode host can mix\nslots with ordinary children (a Card with a `title` slot plus regular body\nparagraphs); a DecoratorNode host has no children channel, so slots are its\nonly editable content (a PullQuote that is otherwise atomic).\n\nA slot value is any non-inline ElementNode or DecoratorNode. The value's\nshape decides the editing model:\n\n- **A bare block** (for example a ParagraphNode) behaves as a single-line\n field with no extra wrapper in the model, the JSON, or the DOM: its virtual\n scope holds exactly one block, so Enter is a no-op (hosts may map it to\n focus movement) and a multi-block paste flattens to inline content the way\n an `` sanitizes its value — line breaks stripped, block-only\n decorators dropped.\n- **A shadow-root container** (an ElementNode whose\n [`isShadowRoot()`](/docs/api/modules/lexical#isshadowroot) returns\n `true`) behaves as a multi-block region with normal block editing inside.\n\n## Declaring and Setting Slots\n\nA host class declares its slot names in [`$config()`](nodes.mdx); values are\nattached with [`$setSlot`](/docs/api/modules/lexical#setslot):\n\n```ts\nimport {\n $create,\n $createParagraphNode,\n $setSlot,\n ElementNode,\n} from 'lexical';\n\nclass CardNode extends ElementNode {\n $config() {\n return this.config('card', {extends: ElementNode, slots: ['title']});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n}\n\nfunction $createCardNode(): CardNode {\n const card = $create(CardNode);\n // Single-line title: the bare paragraph IS the slot value. An empty\n // paragraph is an empty field; to seed default text, append a non-empty\n // TextNode (empty TextNodes are eliminated during reconciliation).\n $setSlot(card, 'title', $createParagraphNode());\n // Ordinary body child, edited like any other block.\n return card.append($createParagraphNode());\n}\n```\n\nFor a multi-block region, use a shadow-root container as the value:\n\n```ts\nclass SlotContainerNode extends ElementNode {\n $config() {\n return this.config('slot-container', {extends: ElementNode});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n isShadowRoot(): boolean {\n return true;\n }\n}\n\n$setSlot(\n pullQuote,\n 'quote',\n $create(SlotContainerNode).append(\n $createParagraphNode().append($createTextNode('First block')),\n $createParagraphNode().append($createTextNode('Second block')),\n ),\n);\n```\n\nThe core API surface (all exported from `lexical`):\n\n- [`$setSlot(host, name, node)`](/docs/api/modules/lexical#setslot) — place a value into a named slot, replacing\n any existing value under that name. Move semantics, mirroring `append`:\n the value is detached from any current parent or slot first. Throws if the\n value is inline or if the name is one of the reserved prototype keys\n (`__proto__`, `constructor`, `prototype`). Slotting a node into its own\n descendant would form a cycle; this is checked (and throws) in development\n only — in production it behaves like appending an ancestor through the\n children channel, which is likewise unguarded.\n- [`$getSlot(host, name)`](/docs/api/modules/lexical#getslot) — the value under a name, or `null`.\n- [`$getSlotNames(host)`](/docs/api/modules/lexical#getslotnames) — the host's slot names in canonical order.\n- [`$removeSlot(host, name)`](/docs/api/modules/lexical#removeslot) — detach the value under a name (the subtree is\n garbage-collected unless you reattach it elsewhere).\n- [`$getSlotHost(node)`](/docs/api/modules/lexical#getslothost) — the host a value is slotted into, or `null`.\n- [`$getSlotNameWithinHost(node)`](/docs/api/modules/lexical#getslotnamewithinhost) — the name of the slot\n a value occupies on its host (the reverse direction of `$getSlotHost`), or\n `null` when the node is not a slot value.\n- [`$getSlotFrame(node)`](/docs/api/modules/lexical#getslotframe) — the innermost slot value containing a node (the\n \"frame\" whose virtual shadow root scopes editing), or `null` when the node\n is not inside any slot.\n- [`$getSelectionSlotFrame(selection)`](/docs/api/modules/lexical#getselectionslotframe) — the slot frame a\n selection lives in, or `null` when it is outside any slot. Selection-driven\n exporters walk this frame instead of the root's children, because a\n selection inside a slot never contains its host and a root walk would\n export nothing. Works for every selection type, not just `RangeSelection`.\n- [`$isSlotHost(node)`](/docs/api/modules/lexical#isslothost) /\n [`$isSlotChild(node)`](/docs/api/modules/lexical#isslotchild) — type guards\n for the [`SlotHostNode`](/docs/api/modules/lexical#slothostnode) /\n [`SlotChildNode`](/docs/api/modules/lexical#slotchildnode) interfaces.\n\n## Slot Order\n\nSlot order is canonical and derived, never stored. Names declared in\n`$config()` (`slots: ['quote', 'attribution']`) sort first in declaration\norder; undeclared names sort after them, lexicographically by UTF-16 code\nunit (plain JavaScript string comparison, locale-independent). `$setSlot`\nre-canonicalizes on every write, so documents normalize on load and\nconcurrent collaborative additions converge to the same order on every\nclient. If presentation order matters, declare the names.\n\n## Rendering\n\nThe reconciler always renders every slot subtree synchronously, but into a\nhidden placeholder container — visibility is the host's explicit decision.\nThere are three ways to attach a slot, all sharing the same contract\n(attaching moves the container to the target, a no-op when it is already\nthere, and reveals it; the container renders as a normal block):\n\n1. **Synchronously in-lexical**: register a `$getSlotTargetElement`\n [`DOMRenderMatch`](/docs/api/modules/lexical_html#domrendermatch)\n override for the host's node class (a\n [DOM render override](../serialization/dom-render.md), not a node\n method — this is an advanced hook). The reconciler consults it whenever\n it creates or reconciles the slot's container and attaches/reveals\n within the same commit — no listener or framework hop. Returning\n `hostDom` reveals the slot in its default slots-first position:\n\n ```ts\n import {domOverride, DOMRenderExtension} from '@lexical/html';\n import {configExtension, defineExtension} from 'lexical';\n\n export const CardExtension = defineExtension({\n dependencies: [\n configExtension(DOMRenderExtension, {\n overrides: [\n domOverride([CardNode], {\n // Reveal the title in its default slots-first position within\n // the same commit that renders it. Returning an element from\n // deeper inside the host's DOM attaches it there instead;\n // $next() defers to lower-priority overrides (default: null,\n // a hidden placeholder).\n $getSlotTargetElement: (node, slotName, hostDom, $next, editor) =>\n hostDom,\n }),\n ],\n }),\n ],\n name: 'card',\n nodes: [CardNode],\n });\n ```\n\n2. **Imperatively**:\n [`mountSlotContainer(editor, nodeKey, slotName, target)`](/docs/api/modules/lexical#mountslotcontainer)\n and\n [`unmountSlotContainer(editor, nodeKey, container)`](/docs/api/modules/lexical#unmountslotcontainer)\n from `lexical` are the framework-independent primitives (e.g. from a\n [mutation listener](/docs/api/modules/lexical#registermutationlistener),\n which fires after the commit). `mountSlotContainer` resolves the container\n against the committed editor state\n ([`editor.getEditorState()`](/docs/api/modules/lexical#geteditorstate)), so\n the model it reads matches the reconciled DOM it reveals;\n `unmountSlotContainer` takes the container you already hold and only touches\n the DOM:\n\n ```ts\n import {mountSlotContainer} from 'lexical';\n\n // e.g. inside an extension's register(editor):\n const unregister = editor.registerMutationListener(\n CardNode,\n (mutations) => {\n for (const [nodeKey, mutation] of mutations) {\n if (mutation === 'destroyed') {\n continue;\n }\n const hostDom = editor.getElementByKey(nodeKey);\n if (hostDom !== null) {\n // Mounting in place: the placeholder is already parked in the\n // host DOM, so this just reveals it in its slots-first position.\n // Any element within the host's DOM works as a target.\n mountSlotContainer(editor, nodeKey, 'title', hostDom);\n }\n }\n },\n {skipInitialization: false},\n );\n ```\n\n `unmountSlotContainer(editor, nodeKey, container)` is the reverse: it\n hides the container and parks it back in the host DOM, for when a mount\n target goes away while the host remains.\n\n3. **From React chrome**: the\n [`useLexicalSlotRef`](/docs/api/modules/lexical_react_useLexicalSlotRef#uselexicalslotref)\n hook from `@lexical/react/useLexicalSlotRef` wraps the imperative pair and returns a\n ref that mounts a slot's container into your component — the usual choice\n for a DecoratorNode host's `decorate()` chrome (whose containers are\n opted back into `contentEditable` automatically, since the decorator DOM\n is non-editable):\n\n```tsx\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {useLexicalSlotRef} from '@lexical/react/useLexicalSlotRef';\n\nfunction PullQuoteComponent({nodeKey}: {nodeKey: NodeKey}) {\n const [editor] = useLexicalComposerContext();\n const quoteRef = useLexicalSlotRef(editor, nodeKey, 'quote');\n const attributionRef = useLexicalSlotRef(\n editor,\n nodeKey,\n 'attribution',\n );\n return (\n
\n
\n
\n
\n );\n}\n```\n\nA `contentEditable=false` ElementNode shell can host React chrome the same\nway (slot containers opt into editing whenever the host DOM is\nnon-editable): the playground's Review demo portals chrome into the host DOM,\nattaches the author slot with `useLexicalSlotRef`, drives an interactive\nstar-rating widget that persists to NodeState, and applies the identical\nhidden-then-attach technique to its `getDOMSlot` children element. Such a shell should call\n[`setDOMUnmanaged(dom)`](/docs/api/modules/lexical#setdomunmanaged) in\n`createDOM` — the portal and the\nattach moves mutate the shell's children from outside the reconciler, and\nthe marker gives the shell the same mutation-observer exemption a\nDecoratorNode's DOM has.\n\n## Editable state\n\nA slot rendered inside a non-editable host (a DecoratorNode, or a\n`contentEditable=false` element shell) would not track the editor's editable\nstate on its own, so the reconciler gives its container an explicit\n`contentEditable` that follows `editor.isEditable()`, and re-renders the islands\nwhenever `setEditable` toggles — so a read-only editor's slots are not left\neditable. No extension is required. Slots always follow the editor; there is\ncurrently no way for a slot to override its own editable state.\n\nA host that attaches its own editable island which is *not* a slot container —\nfor example the Review demo's `getDOMSlot` children element inside its\n`contentEditable=false` shell — opts it into the same behavior with\n[`$markSlotEditable(element, editor)`](/docs/api/modules/lexical#marksloteditable),\nre-applying it from `updateDOM` so an editable toggle reaches the island.\n\n## Editing Behavior\n\n- **Selection never crosses a slot boundary.** Selections are clamped to the\n anchor's slot frame at every entry point (DOM resolution,\n [`$setSelection`](/docs/api/modules/lexical#setselection),\n and point mutation), so a mouse drag and a `shift+arrow` across the\n boundary land on the same clamped result. A focus in a slot of a host is\n moved past the whole host, or to the edge of the host's own children when\n the selection starts inside the host.\n- **Deletion stops at the boundary.** Backspace at the start of a slot and\n forward-Delete at its end are no-ops instead of merging across the virtual\n shadow root.\n- **`Cmd+A` scopes to the slot frame** when the caret is inside one; outside\n slots the default handlers keep the legacy whole-document behavior.\n Progressive expansion (block → enclosing slot frame → document on repeated\n presses) is provided by the opt-in\n [`SelectBlockExtension`](/docs/api/modules/lexical_extension#selectblockextension)\n from `@lexical/extension`.\n- **Generic block conversion skips slot values.** A slot value has no\n parent — its up-link is `$getSlotHost` — so selection-driven block\n converters (`$setBlocksType`, `$wrapNodes`, `$insertList` / `$removeList`,\n the markdown block shortcuts) treat it as ineligible and do nothing rather\n than replace it: the slot assignment is managed by the node or extension\n that owns the slot. Calling `LexicalNode.replace` directly on a slot value\n throws; reassign the slot with `$setSlot` on its host instead.\n- **Slots stay bound to their host through `replace`.** Replacing a slot\n *host* (`host.replace(other)`) does not transfer its slots to the\n replacement — slots are not necessarily portable across node types, so the\n slot map travels with the node, never with its position. If the replaced\n host is reattached in the same update (the\n [`$wrapNodeInElement`](/docs/api/modules/lexical_utils#wrapnodeinelement)\n pattern) it keeps its slots; if it stays detached, its slot subtrees are\n garbage-collected with it. The same applies to anything built on `replace`:\n converting a slot host with `$setBlocksType` produces a slot-less\n replacement block. Move a slot onto another host explicitly with\n `$setSlot`.\n- **A NodeSelection of an element carries its children.** Copy and export\n of a whole-host NodeSelection (e.g. a chrome click that selects \"the whole\n Card\") include the host's body children even though they aren't in the\n selection themselves — the old shell-only output made cut silently lossy.\n This applies only to NodeSelection; a partial RangeSelection over the host\n keeps per-child slicing.\n\n### Traversal is intentionally asymmetric\n\nContent reads include slot subtrees, slots-first:\n[`getTextContent()`](/docs/api/modules/lexical#gettextcontent),\n[`getAllTextNodes()`](/docs/api/modules/lexical#getalltextnodes),\nand the [`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots)\nfamily in `@lexical/utils` count slot content for search, copy, and\naccessibility. Navigation excludes them:\n[`getChildren()`](/docs/api/modules/lexical#getchildren),\n[`getFirstDescendant()`](/docs/api/modules/lexical#getfirstdescendant)\nand friends stay linked-list-only, so caret movement never walks into a slot\nby accident. Choose [`$dfs`](/docs/api/modules/lexical_utils#dfs) or\n[`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots) depending on whether \"this subtree\" should mean the\nnavigable tree or all content.\n\n## Serialization\n\nJSON serialization is automatic in both directions. A host's slots serialize\nunder the reserved `$slots` key on\n[`SerializedLexicalNode`](/docs/api/modules/lexical#serializedlexicalnode)\n(a sibling of\nNodeState's reserved `'$'` key), keyed by slot name:\n\n```json\n{\n \"type\": \"card\",\n \"version\": 1,\n \"$slots\": {\n \"title\": {\"type\": \"paragraph\", \"children\": [], \"version\": 1}\n },\n \"children\": []\n}\n```\n\nParsing re-attaches each subtree with `$setSlot` and throws if `$slots`\nappears on a node that cannot host slots. The `$` prefix keeps the\nframework-owned key from colliding with a subclass that already serializes a\n`slots` property of its own.\n\nHTML serialization is opt-in per host, like NodeState: the exporter never\ndescends into slots on its own. A host's `exportDOM` can emit each slot into\na wrapper using\n[`$appendNodeToHTML`](/docs/api/modules/lexical_html#appendnodetohtml) from\n`@lexical/html`, and a\n[DOM import rule](../serialization/dom-import.md) on the host's\ndistinguishing markup maps the wrappers back through `$setSlot`.\n\n## Collaboration\n\nSlots sync on both the V1 and V2 Yjs bindings through a per-slot-diffed\n`Y.Map` stored under the reserved `__slots` attribute key on the host's shared\ntype (the channel reuses the host's `__slots` field name, which is already\nexcluded from the property sync). Hosts with declared slots create that map\neagerly, so two clients\nconcurrently setting *different* slot names for the first time merge\nper-entry instead of racing. Malformed or hostile remote entries are\nvalidated and skipped.\n\n:::caution\n\nPre-slots clients receiving slot data from upgraded peers will error rather\nthan render it. Enabling slots in long-lived shared documents should be\ngated on all participants running a slots-aware version; new clients\ntolerate unknown slot data going forward.\n\n:::\n\n## Reserved Names\n\nAdding slots reserves a few identifiers that custom node subclasses should\nnot define for their own purposes:\n\n- the `__slots` and `__slotHost` fields on ElementNode / DecoratorNode — the\n `__slots` name is also the collab attribute key for the slots channel, so it\n is reserved on the Yjs shared type too;\n- the `$slots` serialized JSON key.\n\n## Current Limitations\n\n- The caret / NodeCaret APIs throw across a slot boundary (\"no common\n ancestor\"); slot-aware caret traversal is a planned follow-up.\n- Nested slots (a slot whose host is itself slotted) are only handled one\n level deep by the runtime selection comparator.\n- The mixed-version collab caveat above.\n","isInternal":false,"tokens":4854,"sizeBytes":20630},{"name":"node-cloning.md","path":"packages/lexical-website/docs/concepts/node-cloning.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/node-cloning.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Node Cloning\n\nUnderstanding how to properly clone and modify nodes is crucial for working with Lexical. This guide explains the different cloning mechanisms and when to use each one.\n\n## Types of Node Cloning\n\nLexical provides several ways to clone nodes, each serving a different purpose:\n\n1. `static clone()` - Internal API for state management\n2. `$copyNode()` - Public API for creating new nodes\n3. `getWritable()` - Public API for node modifications\n\n## The `clone` Method\n\n### What is `clone`?\n\nThe `clone` method is a static method that creates the next version of a node. A node that declares [`$config()`](./nodes.mdx) has one synthesized for it and need not implement it — a hand-written `clone` is only required for a node that does not use `$config()`, or whose constructor has required arguments. Either way, it's important to understand that this is an **internal API** used by Lexical's state management system.\n\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n // ✅ Correct implementation\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### When is `clone` Used?\n\n1. **Internal State Management**\n - Used by Lexical internally\n - Part of the editor's state update system\n - Called by `getWritable()`\n\n2. **Node Mutations**\n ```typescript\n // Example of a node method implementation\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n }\n\n node.setData(\"new data\");\n ```\n\n### When NOT to Use `clone`?\n\n```typescript\n// ❌ Never do this\nfunction $duplicateNode(node: MyCustomNode) {\n return MyCustomNode.clone(node); // Don't call clone directly\n}\n```\n\n## The `afterCloneFrom` Method\n\n### What is `afterCloneFrom`?\n\n`afterCloneFrom(prevNode)` runs on every clone, right after it is constructed,\nand copies over whatever the constructor did not. The base implementation\ncarries the node's links to its parent and siblings and its\n[NodeState](./node-state.md), and `ElementNode` and `TextNode` carry their own\nbuilt-in properties such as format, style, and indent. A property that is\ncopied neither by the constructor nor by some `afterCloneFrom` silently\nreverts to its default on the node's next write.\n\n### When you don't need it\n\nWith the modern APIs you usually don't write one at all:\n\n- **Serialization schema.** A property declared as a field in a `$config`\n [`json` schema](./nodes.mdx#creating-custom-nodes-with-a-serialization-schema)\n (`withField(stringValue(), {field: '__label'})`) is carried across the\n clone for you, because the schema says where it is stored. Available in\n Lexical v0.51.0 and later.\n- **NodeState.** State created with `createState` and stored with `$setState`\n is carried by the base `afterCloneFrom`, so a node whose extra data lives\n only in NodeState needs nothing.\n\n```ts\n// At module scope, above the class, so TypeScript checks it against the class\nconst calloutSchema = nodeSchema()({\n label: withField(stringValue(), {field: '__label'}),\n});\n\nclass CalloutNode extends ElementNode {\n __label: string = '';\n\n // No afterCloneFrom: `__label` is declared as a field in calloutSchema, so\n // it is carried across every clone.\n $config() {\n return this.config('callout', {extends: ElementNode, json: calloutSchema});\n }\n}\n```\n\n### When you still need it\n\nOverride `afterCloneFrom` for a property that neither of those covers: a\nfield that isn't in the node's schema, one declared only through accessor\nmethods (see\n[Carrying properties across a clone](../serialization/serialization.md#carrying-properties-across-a-clone)),\nor any property of a node written without a schema. Always call\n`super.afterCloneFrom(prevNode)` first so the inherited properties and\nNodeState are still carried:\n\n```ts\nclass MyCustomNode extends ElementNode {\n __data: string = '';\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__data = prevNode.__data;\n }\n}\n```\n\nLike `clone`, `afterCloneFrom` is called by Lexical; don't call it yourself\nexcept through `super`.\n\n## Using `$copyNode`\n\n### What is `$copyNode`?\n\n`$copyNode` is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node.\nBy default, all properties and `NodeState` will be copied to the new node, and then `resetOnCopyNodeFrom` will be called to\nallow the node to optionally reset certain properties (and NodeState configured with `resetOnCopyNode: true`) to defaults\n(such as the checked state of a `ListItemNode`).\n\n```typescript\n// ✅ Correct: Using $copyNode\nconst copy = $copyNode(existingNode);\n```\n\n### When to Use `$copyNode`?\n\n1. **Creating Duplicates**\n ```typescript\n // ✅ Correct: Duplicating a node\n const duplicate = $copyNode(originalNode);\n someParent.append(duplicate);\n ```\n\n## Using `getWritable`\n\n### What is `getWritable`?\n\n`getWritable` is an internal API used within node method implementations to get a mutable version of a node. Node consumers should use the node's public methods instead.\n\n```typescript\n// ✅ Correct: Implementation of a node method\nclass MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n}\n\n// ✅ Correct: Using the node\nconst node = new MyCustomNode();\nnode.setData(\"new value\");\n```\n\n## Common Patterns\n\n### Modifying Nodes\n\n```typescript\n// ✅ Correct: Modifying a node\nfunction $updateNodeData(node: MyCustomNode, newData: string): MyCustomNode {\n return node.setData(newData);\n}\n\n// ❌ Incorrect: Don't clone manually\nfunction $updateNodeDataWrong(node: MyCustomNode, newData: string): MyCustomNode {\n const clone = MyCustomNode.clone(node);\n clone.setData(newData);\n return clone;\n}\n```\n\n### Copying Nodes\n\n```typescript\n// ✅ Correct: Copying a node\nfunction $duplicateNode(node: MyCustomNode): MyCustomNode {\n return $copyNode(node);\n}\n\n// ❌ Incorrect: Don't use clone\nfunction $duplicateNodeWrong(node: MyCustomNode): MyCustomNode {\n return node.constructor.clone(node);\n}\n```\n\n## Performance Considerations\n\n1. **Referential Integrity**\n - `getWritable()` ensures proper EditorState updates with new clones\n - Prevents \"orphaned\" nodes that won't be rendered\n\n2. **State Management**\n ```typescript\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data; // Properly tracked by editor\n return self;\n }\n }\n ```\n\n## Testing\n\n```typescript\ntest('node modification', async () => {\n await editor.update(() => {\n const node = new MyCustomNode(\"test\");\n \n node.setData(\"new data\");\n \n // ✅ Correct: Use $copyNode for duplication\n const copy = $copyNode(node);\n });\n});\n```\n\n## Related Concepts\n\n- [Editor State](editor-state.md) - How cloning affects editor state\n- [Nodes](nodes.mdx) - Core concepts about Lexical nodes\n\n## Common Questions\n\n**Q: How do I duplicate a node?**\nA: Use `$copyNode(node)` to create a new copy with a new key.\n\n**Q: When should I use clone?**\nA: Never directly. Use `$copyNode()` or `getWritable()` instead. ","isInternal":false,"tokens":1768,"sizeBytes":7286},{"name":"node-replacement.md","path":"packages/lexical-website/docs/concepts/node-replacement.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/node-replacement.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Node Replacement\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a subclass.\n\n## Use Case\n\n:::note\n\nIn earlier versions of this documentation, \"Node Replacement\" was called \"Node Overrides\".\nWe've changed the name to match the terms used in the implementation.\n\n:::\n\n:::tip\n\nIf your use case only requires adding ad-hoc data to existing nodes, you may be able to use the [NodeState](node-state.md) API instead of subclassing and node replacement.\n\n:::\n\nSome of the most commonly used Lexical Nodes are owned and maintained by the core library. For example, ParagraphNode, HeadingNode, QuoteNode, List(Item)Node etc - these are all provided by Lexical packages, which provides an easier out-of-the-box experience for some editor features, but makes it difficult to override their behavior. For instance, if you wanted to change the behavior of ListNode, you would typically extend the class and override the methods. However, how would you tell Lexical to use *your* ListNode subclass in `ListExtension` instead of using the core ListNode? That's where Node Replacement can help.\n\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a different node class. This can be done through the `nodes` of an extension:\n\n```ts\nconst CustomParagraphExtension = defineExtension({\n name: '@my-app/CustomParagraph',\n nodes: () => [\n // Don't forget to register your custom node separately!\n CustomParagraphNode,\n {\n replace: ParagraphNode,\n with: (node: ParagraphNode) => {\n return $createCustomParagraphNode();\n },\n withKlass: CustomParagraphNode,\n },\n ],\n});\n```\nIn the snippet above,\n- `replace`: Specifies the core node type to be replaced. \n- `with`: Defines a transformation function to replace instances of the original node to the custom node. \n- `withKlass`: This option ensures that behaviors associated with the original node type work seamlessly with the replacement. For instance, node transforms or mutation listeners targeting ParagraphNode will also apply to CustomParagraphNode when withKlass is specified. Without this option, the custom node might not fully integrate with the editor's built-in features, leading to unexpected behavior.\n\nOnce this is done, Lexical will replace all ParagraphNode instances with CustomParagraphNode instances. One important use case for this feature is overriding the serialization behavior of core nodes. Check out the full example below.\n\n## Node Replacement Example\n\nThis example demonstrates using Node Replacement to replace all `ParagraphNode` with a `CustomParagraphNode` that overrides `createDOM`.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-replacement?file=src/main.tsx)\n\n\n","isInternal":false,"tokens":699,"sizeBytes":3272},{"name":"node-state.md","path":"packages/lexical-website/docs/concepts/node-state.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/node-state.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# NodeState\n\nThe NodeState API introduced in v0.26.0 allows arbitrary state to be added\nad-hoc to any node in a way that participates with reconciliation, history,\nand JSON serialization.\n\n## Use Case\n\nNodeState allows your application to define keys that can be stored on\nany node with automatic JSON support.\n\n:::tip\n\nYou can even add node state to the RootNode to store document-level metadata.\n\n:::\n\nWith a combination of NodeState and other APIs such as\n[Listeners](listeners.md) or\n[Transforms](transforms.md) you can\nlikely shape the editor to meet your needs without having to do much\n[Node Customization](node-replacement.md).\n\nEven when you are subclassing nodes, using NodeState instead of additional\nproperties to store the node's data can be [more efficient](#efficiency)\nand will save you from writing a lot of boilerplate in the constructor,\nupdateFromJSON, and exportJSON.\n\n## Usage\n\n### createState\n\n[createState](/docs/api/modules/lexical#createstate)\ncreates a\n[StateConfig](/docs/api/modules/lexical#stateconfig)\nwhich defines the key and configuration for your NodeState value.\n\nThe key must be locally unique, two distinct StateConfig must not have the\nsame string key if they are to be used on the same node.\n\nTypical usage will look something like this:\n\n```ts\nconst questionState = createState('question', {\n parse: (v) => (typeof v === 'string' ? v : ''),\n});\n```\n\nThe required `parse` function serves two purposes:\n- It provides a type-safe and runtime-safe way to parse values that were\n serialized to JSON\n- When called with `undefined` (or any invalid value) it should return some\n default value (which may be `undefined` or `null` or any other value you\n choose)\n\nIn this case, the question must be a string, and the default is an\nempty string.\n\nSee the\n[createState](/docs/api/modules/lexical#createstate)\nAPI documentation for more details, there are other optional settings\nthat you may want to define particularly if the value is not a primitive\nvalue such as boolean, string, number, null, or undefined.\n\n:::tip\n\nInstead of writing parse functions by hand, use the\n[serialization schema combinators](/docs/serialization/#declarative-serialization-schemas-with-config)\nfrom `lexical`, such as `stringValue`, `numberValue`, `enumValue`,\n`arrayValue`, `objectValue`, and `nullable`. They are the same ones a node's\n`$config` JSON schema uses. A schema is itself a parse function, so it can be\npassed directly as `parse`:\n\n```ts\nimport {arrayValue, createState, stringValue} from 'lexical';\n\nconst questionState = createState('question', {parse: stringValue()});\nconst tagsState = createState('tags', {parse: arrayValue(stringValue())});\n```\n\nBecause `parse` is just a function, the combinators also compose with schema\nlibraries such as [zod](https://zod.dev/), [ArkType](https://arktype.io/),\n[Effect](https://effect.website/), and [Valibot](https://valibot.dev/). Wrap a\nlibrary's validator in a parse function that returns a default for invalid\ninput, or use `transformValue` to refine what a combinator parsed.\n\n:::\n\n### $getState\n\n[$getState](/docs/api/modules/lexical#getstate) gets the\nNodeState value from the given node, or the default if that key was never\nset on the node.\n\n```ts\nconst question = $getState(pollNode, questionState);\n```\n\nSee also\n[$getStateChange](/docs/api/modules/lexical#getstatechange)\nif you need an efficient way to determine if the state has changed on two\nversions of the same node (typically used in updateDOM, but may be useful in\nan update listener or mutation listener).\n\n### $setState\n\n[$setState](/docs/api/modules/lexical#setstate) sets the\nNodeState value on the given node.\n\n```ts\nconst question = $setState(\n pollNode,\n questionState,\n 'Are you planning to use NodeState?',\n);\n```\n\n:::tip\n\nThe last argument is a ValueOrUpdater, just like with React's useState\nsetters. If you use an updater function and the value does not change,\nthe node and its NodeState *won't* be marked dirty.\n\n:::\n\n## Serialization\n\nThe NodeState for a node, if any values are set to non-default values, is\nserialized to a record under a single\n[NODE_STATE_KEY](/docs/api/modules/lexical#node_state_key)\nwhich is equal to `'$'`.\n\n```json\n{\n \"type\": \"poll\",\n \"$\": {\n \"question\": \"Are you planning to use NodeState?\"\n }\n}\n```\n\n:::tip\n\nBy default, it is assumed that your parsed values are JSON serializable,\nbut for advanced use cases you may use values such as Date, Map, or Set\nthat need to be transformed before JSON serialization. See the\n[StateValueConfig](/docs/api/modules/lexical#statevalueconfig)\nAPI documentation.\n\n:::\n\n### Flat serialization with `$config`\n\nNodes that declare a `StateConfig` in [`$config`](nodes.mdx#creating-custom-nodes-with-config-and-nodestate)\nwith `flat: true` lift that key to the top level of the serialized node\ninstead of nesting it under `'$'`. This makes the JSON shape identical\nto a legacy node that stored the value as a `__property` instance\nvariable, so existing payloads continue to round-trip after the node is\nmigrated to NodeState.\n\nFor example, a `ColoredNode` that extends `TextNode` and declares a flat\n`color` state (see [Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\n$config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n}\n```\n\nserializes as:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"color\": \"red\"\n}\n```\n\nA non-flat (default) state on the same node would instead appear under\n`'$'`:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"$\": {\n \"color\": \"red\"\n }\n}\n```\n\nIn both cases, a key is only emitted when the current value is not equal\nto the default returned by its `parse` function — see\n[Efficiency](#efficiency).\n\n:::note\n\nDon't reuse a flat key that a superclass already serializes (e.g. `text`\non `TextNode`).\n\n:::\n\n### Upgrading a legacy JSON property to NodeState\n\nA node that stores data as a `__property` instance variable with custom\n`exportJSON`/`importJSON`/`updateFromJSON` can be migrated to NodeState\nwith `flat: true` without changing its serialized JSON shape.\n\nBefore — `ColoredNode` with a `__color` property and hand-written\nserialization (see the full legacy example in\n[Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\nexport type SerializedColoredNode = Spread<\n {color?: string},\n SerializedTextNode\n>;\n\nexport class ColoredNode extends TextNode {\n __color: string;\n\n constructor(text: string = '', color: string = DEFAULT_COLOR, key?: NodeKey) {\n super(text, key);\n this.__color = color;\n }\n\n static getType(): string {\n return 'colored';\n }\n\n static clone(node: ColoredNode): ColoredNode {\n return new ColoredNode(node.__text, node.__color, node.__key);\n }\n\n static importJSON(serializedNode: SerializedColoredNode) {\n return new ColoredNode().updateFromJSON(serializedNode);\n }\n\n updateFromJSON(serializedNode: SerializedColoredNode) {\n const self = super.updateFromJSON(serializedNode);\n self.__color =\n typeof serializedNode.color === 'string'\n ? serializedNode.color\n : DEFAULT_COLOR;\n return self;\n }\n\n exportJSON(): SerializedColoredNode {\n return {\n ...super.exportJSON(),\n color: this.__color === DEFAULT_COLOR ? undefined : this.__color,\n };\n }\n}\n```\n\nAfter — same on-the-wire JSON, no hand-written serialization:\n\n```ts\nconst colorState = createState('color', {\n parse: (v) => (typeof v === 'string' ? v : DEFAULT_COLOR),\n});\n\nexport class ColoredNode extends TextNode {\n $config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n }\n}\n```\n\nNo `exportJSON`, `importJSON`, `updateFromJSON`, `clone`, or\n`afterCloneFrom` override is needed: `$config` installs `clone` and\n`importJSON`, and the base `exportJSON`/`updateFromJSON`/`afterCloneFrom`\non `LexicalNode`/`TextNode` already round-trip NodeState. Read the color\nvia `$getState(node, colorState)` and write it via\n`$setState(node, colorState, value)` instead of `node.__color`.\n\n:::tip\n\nFor a seamless migration, keep the JSON key name the same — for a flat\nstate, that's the first argument to `createState`. Migrating from a\nnon-flat NodeState to a flat NodeState also works: state that appears\nunder the `$` (`NODE_STATE_KEY`) is still parsed even when the state is\nconfigured as flat, and the flat value takes precedence when both are\npresent.\n\n:::\n\n## Efficiency\n\nNodeState uses a copy-on-write scheme to manage each node's state. If\nnone of the state has changed, then the NodeState instance will be\nshared across multiple versions of that node.\n\n:::info\n\nIn a given reconciliation cycle, the first time a Lexical node is marked dirty\nvia `getWritable` will create a new instance of that node. All properties\nof the previous version are set on the new instance. NodeState is stored\nas a single property, and no copying of the internal state is done\nuntil the NodeState itself is marked writable.\n\n:::\n\nWhen serializing to JSON, each key will only be stored if the value\nis not equal to the default value. This can save quite a lot of space\nand bandwidth.\n\nParsing and serialization is only done at network boundaries, when\nintegrating with JSON or Yjs. When a value changes from an external\nsource, it is only parsed once the first time it is read.\nValues that do not come from external sources are not parsed, and\nvalues that are not used are never parsed.\n\n## Capabilities\n\nCurrent:\n\n- Allows you to define and add state to any node\n- Serializes that state automatically in the node's JSON, supporting\n versioning and copy+paste\n- Works with the reconciler, TextNodes with differing state will not\n be implicitly merged\n- @lexical/yjs support, NodeState will be automatically synchronized\n like any other property\n- NodeState values that are not used will simply pass-through, making\n it a bit easier for situations where multiple configurations are used\n on the same data (e.g. older and newer versions of your editor,\n a different set of plugins based on context, etc.).\n- Pre-registration system for nodes to declare expected state\n and serialize them as top-level properties (`flat`) with `$config`\n (see [#7260](https://github.com/facebook/lexical/issues/7260)).\n- Can be integrated with\n [DOMRenderExtension](../serialization/dom-render.md) for editor\n rendering and HTML export\n- Can be integrated with\n [DOMImportExtension](../serialization/dom-import.md) for HTML import\n\nFuture:\n\n- Does not yet support direct integration with Yjs, e.g.\n you can not store a Y.Map as a NodeState value\n (see [#7293](https://github.com/facebook/lexical/issues/7293))\n\n## Node State Style Example\n\nThis example demonstrates an advanced use case of storing a style object on TextNode using NodeState.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-state-style?file=src/main.tsx)\n\n\n","isInternal":false,"tokens":2790,"sizeBytes":11450},{"name":"one-lexical-per-app.md","path":"packages/lexical-website/docs/concepts/one-lexical-per-app.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/one-lexical-per-app.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"---\nsidebar_label: One Lexical per app\n---\n\n# One Lexical per app\n\n`lexical` is effectively a singleton **within one app**: an app must resolve\nexactly **one** copy of `lexical`, and one copy of each `@lexical/*` package it\nuses. Two copies in the same bundle do not merely waste bytes — they break the\neditor in ways whose error messages point nowhere near the real cause.\n\nThe practical consequence, covered in [Publishing a library](#publishing-a-library)\nbelow: **a library built on Lexical declares `lexical` and the `@lexical/*`\npackages it imports as `peerDependencies`, never as `dependencies`. The\napplication brings its own Lexical.**\n\n:::note\n\nThis page is about npm `peerDependencies` in your `package.json`. Extensions\nhave their own, unrelated notion of\n[peer dependencies](../extensions/peer-dependencies.md) — optional links between\nextensions inside one editor.\n\n:::\n\n## The boundary is the app, not the page\n\nSeveral self-contained apps can share a page, each with its own bundled copy of\nLexical, and that is fine — a CMS page with two independently deployed widgets\non it, or a micro-frontend setup, does not have a bug just because two copies of\n`lexical` are loaded. Lexical anticipates this: `isLexicalEditor()` is an\n`instanceof` check specifically \"to prevent issues with multiple embedded\nLexical installations\", and an editor is tagged on its own root element rather\nthan in any page-global registry, so each app's editors resolve to that app's\nLexical and ignore the others.\n\nWhat those apps cannot do is interoperate. Two copies have no compatible API\nsurface between them, so treat each as a sealed island:\n\n- do not pass nodes, editors, `EditorState` objects, selections or commands\n across the boundary — pass serialized JSON or HTML, which is data rather than\n identity;\n- a plugin, node package or shared editor config must be bundled with the app it\n serves, not shared as a live import between apps;\n- `@lexical/react` context does not cross the boundary either, since the context\n object itself comes from one copy.\n\nThe rest of this page is about the failure case: two copies **inside one app**,\nwhere code from copy A is expected to work with an editor from copy B.\n\n## Why one copy per app\n\nLexical keeps state at module scope, and identifies things by reference rather\nthan by name. Both assumptions hold only within a single copy of the module.\n\n- **The active editor is module state.** `activeEditor`, `activeEditorState`\n and `isReadOnlyMode` live at module scope in `LexicalUpdates.ts`, and every\n `$` function reads them. `editor.update()` in copy A sets copy A's variables;\n a `$` function imported from copy B reads copy B's, which are still `null`\n ([Editor State](editor-state.md)).\n- **Node classes are compared by identity.** Node registration and the\n `instanceof LexicalNode` checks compare class references. A node that extends\n `LexicalNode` from copy A is not, as far as copy B is concerned, a\n `LexicalNode` at all — even though both classes have the same name and come\n from the same published version ([Nodes](nodes.mdx)).\n- **Commands are object identities.** `createCommand()` returns a fresh `{type}`\n object, and `registerCommand`/`dispatchCommand` match on that object, not on\n its `type` string. Two copies of `lexical` export two distinct\n `FORMAT_TEXT_COMMAND` objects, so a dispatch from one never reaches a listener\n registered with the other ([Commands](commands.md)).\n\nOn top of that, two copies are usually two *versions*, which is API drift inside\na single editor: half your plugins were compiled against a different API and\nserialization format than the editor running them, and the mismatch surfaces\nonly at runtime, on the paths that happen to differ.\n\n## Symptoms of a duplicated Lexical\n\nThe errors are unhelpfully literal — a class that plainly does implement\n`getType()` is reported as not implementing it, because the check is running\nagainst the other copy:\n\n```\nLexicalNode: Node FooNode does not implement .getType().\n\nCreate node: Type heading in node HeadingNode does not match registered node\nHeadingNode with the same type\n\ncreateEditor: nodes[0] FooNode (type foo) is not a constructor that subclasses\nLexicalNode from the lexical package used by this editor (0.50.0)\n\nUnable to find an active editor state. State helpers or node methods can only be\nused synchronously during the callback of editor.update(), editor.read(), or\neditorState.read(). Detected on the page: 0 compatible editor(s) with version\n0.50.0 and incompatible editors with versions 0.49.0\n```\n\nThat last sentence is Lexical telling you directly that it found editors built\nfrom another copy — a version different from its own, or the same version marked\n`(separately built, likely a bundler configuration issue)`. Note that this\ndiagnostic scans the whole page, so a genuinely separate app that ships its own\nLexical is counted there too; it is evidence of a bug only when those editors\nwere supposed to be part of *your* app.\n\nSilent failures look like: a command that dispatches but never fires its\nlistener, `$getSelection()` returning `null` inside an update, or a custom node\nrendering as plain text after a copy/paste. Real reports of this failure mode:\n[#4225](https://github.com/facebook/lexical/issues/4225) and\n[#7819](https://github.com/facebook/lexical/issues/7819).\n\n## Publishing a library\n\nIf you publish a package that imports from `lexical` or `@lexical/*` — a plugin,\na node package, a shared editor config, an in-house wrapper in a monorepo — put\nthose packages in `peerDependencies`, and in `devDependencies` so you can still\nbuild and test:\n\n```json\n{\n \"name\": \"my-lexical-plugin\",\n \"peerDependencies\": {\n \"lexical\": \">=0.50.0\",\n \"@lexical/react\": \">=0.50.0\",\n \"@lexical/utils\": \">=0.50.0\"\n },\n \"devDependencies\": {\n \"lexical\": \"0.50.0\",\n \"@lexical/react\": \"0.50.0\",\n \"@lexical/utils\": \"0.50.0\"\n }\n}\n```\n\nNotes on the ranges:\n\n- Lexical is pre-1.0, so `^0.50.0` means `>=0.50.0 <0.51.0` — a caret peer range\n locks your users out of the next release. Prefer an open `>=` range (or an\n explicit `>=0.50.0 <1.0.0`) so an app can upgrade Lexical without waiting for\n you.\n- Mark a peer optional with\n [`peerDependenciesMeta`](https://docs.npmjs.com/cli/configuring-npm/package-json#peerdependenciesmeta)\n when the import is behind an opt-in entry point, the way this repo's own\n packages mark `typescript` optional.\n- Do not add `lexical` to `dependencies` \"just so it installs\". That is exactly\n what pins a second copy under `node_modules/your-lib/node_modules/lexical` as\n soon as your range and the app's range disagree.\n\n## Application setup\n\nThe application owns the version, and every Lexical package it installs moves\ntogether:\n\n- Install `lexical` and each `@lexical/*` package you use **at the same\n version**. Published `@lexical/*` packages depend on the exact matching\n `lexical` version (the monorepo's `workspace:*` is rewritten to an exact\n version at publish time), so `@lexical/react@0.50.0` beside `lexical@0.49.0`\n guarantees a nested second copy.\n- Verify there is only one **per app**, from the app root:\n\n ```sh\n npm ls lexical @lexical/react # or: pnpm why lexical / yarn why lexical\n ```\n\n More than one resolved version, or a path with a nested `node_modules/lexical`\n in it, is the bug.\n- In a monorepo or a linked-package setup (`npm link`, `pnpm link`, a Yalc\n copy), the linked library resolves Lexical from *its own* `node_modules` and\n duplicates are the default rather than the exception. Deduplicate explicitly:\n hoist the dependency to the workspace root, or force resolution with\n [pnpm `overrides`](https://pnpm.io/settings#overrides), Yarn `resolutions`, or\n `npm dedupe`.\n- Bundlers can also be told to collapse duplicates — Vite\n [`resolve.dedupe`](https://vite.dev/config/shared-options.html#resolve-dedupe),\n webpack `resolve.alias` pointing each package at one path:\n\n ```js\n // vite.config.js\n export default {\n resolve: {dedupe: ['lexical', '@lexical/react', '@lexical/utils']},\n };\n ```\n\n Treat that as a safety net, not a fix: it collapses copies that are already\n version-compatible, and cannot rescue two genuinely different versions.\n- Duplication does not always come from the dependency tree: importing Lexical\n through both `import` and `require` pulls in the ESM and the CJS build of the\n *same* version, which are still two copies. The\n [React FAQ](../react/faq.md#lexicalcomposercontextuselexicalcomposercontext-cannot-find-a-lexicalcomposercontext)\n covers how this one shows up in `@lexical/react`.\n","frontmatter":{"sidebar_label":"One Lexical per app"},"isInternal":false,"tokens":2113,"sizeBytes":8637},{"name":"read-only.md","path":"packages/lexical-website/docs/concepts/read-only.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/read-only.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"\n\n# Read Mode / Edit Mode\n\nLexical supports two modes:\n\n- Read mode\n- Edit mode\n\nThe default behavior for Lexical is edit mode, or more accurately not read only mode. Under-the-hood, the main\nimplementation detail is that the `contentEditable` is being set to `\"false\"` or `\"true\"` depending on the mode.\nSpecific plugins can listen to the mode change too – allowing them to customize parts of the UI depending on the\nmode.\n\n## Setting the mode\n\nIn order to set the mode, this can be done on creation of the editor, with the\n`editable` property of your app's extension:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [RichTextExtension],\n editable: false,\n name: '@my-app/editor',\n }),\n);\n```\n\nWith React, pass the same extension to ``:\n\n```jsx\n\n ...\n\n```\n\nAfter an editor is created, the mode can be changed imperatively:\n\n```js\neditor.setEditable(true);\n```\n\n## Reading the mode\n\nIn order to find the current mode of the editor you can use:\n\n```js\nconst isEditable = editor.isEditable(); // Returns true or false\n```\n\nYou can also get notified when the editor's read only mode has changed:\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (isEditable) => {\n // The editor's mode is passed in!\n console.log(isEditable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\nIn an extension, depend on\n[`WatchEditableExtension`](/docs/api/modules/lexical_extension#watcheditableextension),\nwhose output is a signal holding the current editable state, instead of\nregistering the listener yourself.\n","isInternal":false,"tokens":424,"sizeBytes":1892},{"name":"selection.md","path":"packages/lexical-website/docs/concepts/selection.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/selection.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"# Selection\n\n## Types of selection\n\nLexical's selection is part of the `EditorState`. This means that for every update, or change to the editor, the\nselection always remains consistent with that of the `EditorState`'s node tree.\n\nIn Lexical, there are four types of selection possible:\n\n- `RangeSelection`\n- `NodeSelection`\n- `TableSelection` (implemented in `@lexical/table`)\n- `null`\n\nIt is possible, but not generally recommended, to implement your own selection types that implement `BaseSelection`.\n\n### `RangeSelection`\n\nThis is the most common type of selection, and is a normalization of the browser's DOM Selection and Range APIs.\n`RangeSelection` consists of three main properties:\n\n- `anchor` representing a `RangeSelection` point\n- `focus` representing a `RangeSelection` point\n- `format` numeric bitwise flag, representing any active text formats\n\nBoth the `anchor` and `focus` points refer to an object that represents a specific part of the editor. The main properties of a `RangeSelection` point are:\n\n- `key` representing the `NodeKey` of the selected Lexical node\n- `offset` representing the position from within its selected Lexical node. For the `text` type this is the character, and for the `element` type this is the child index from within the `ElementNode`\n- `type` representing either `element` or `text`.\n\n### `NodeSelection`\n\nNodeSelection represents a selection of multiple arbitrary nodes. For example, three images selected at the same time.\n\n- `getNodes()` returns an array containing the selected LexicalNodes\n\n### `TableSelection`\n\nTableSelection represents a grid-like selection like tables. It stores the key of the parent node where the selection takes place and the start and end points.\n`TableSelection` consists of three main properties:\n\n- `tableKey` representing the parent node key where the selection takes place\n- `anchor` representing a `TableSelection` point\n- `focus` representing a `TableSelection` point\n\nFor example, a table where you select row = 1 col = 1 to row 2 col = 2 could be stored as follows:\n- `tableKey = 2` table key\n- `anchor = 4` table cell (key may vary)\n- `focus = 10` table cell (key may vary)\n\nNote that `anchor` and `focus` points work the same way as `RangeSelection`.\n\n### `null`\n\nThis is for when the editor doesn't have any active selection. This is common for when the editor has been blurred or when selection\nhas moved to another editor on the page. This can also happen when trying to select non-editable components within the editor space.\n\n## Working with selection\n\nSelection can be found using the `$getSelection()` helper, exported from the `lexical` package. This function can be used within\nan update, a read, or a command listener.\n\n:::tip\n\nTo walk the document from a selection point — or to write a traversal that\nhandles empty nodes and collapsed selections correctly — see\n[Node Traversals with NodeCaret](./traversals.md).\n`$caretRangeFromSelection(selection)` converts a `RangeSelection` into the\ncaret range that traversal API works with, and\n`$setSelectionFromCaretRange(range)` converts back.\n\n:::\n\n```js\nimport {$getSelection, SELECTION_CHANGE_COMMAND} from 'lexical';\n\neditor.update(() => {\n const selection = $getSelection();\n});\n\neditorState.read(() => {\n const selection = $getSelection();\n});\n\n// SELECTION_CHANGE_COMMAND runs before reconciliation in the pending update.\neditor.registerCommand(SELECTION_CHANGE_COMMAND, () => {\n const selection = $getSelection();\n});\n```\n\nIn some cases you might want to create a new type of selection and set the editor selection to\nbe that. This can only be done in update or command listeners.\n\n```js\nimport {$setSelection, $createRangeSelection, $createNodeSelection} from 'lexical';\n\neditor.update(() => {\n // Set a range selection\n const rangeSelection = $createRangeSelection();\n $setSelection(rangeSelection);\n\n // You can also indirectly create a range selection, by calling some of the selection\n // methods on Lexical nodes.\n const someNode = $getNodeByKey(someKey);\n\n // On element nodes, this will create a RangeSelection with type \"element\",\n // referencing an offset relating to the child within the element.\n // On text nodes, this will create a RangeSelection with type \"text\",\n // referencing the text character offset.\n someNode.select();\n someNode.selectPrevious();\n someNode.selectNext();\n\n // You can use this on any node.\n someNode.selectStart();\n someNode.selectEnd();\n\n // Set a node selection\n const nodeSelection = $createNodeSelection();\n // Add a node key to the selection.\n nodeSelection.add(someKey);\n $setSelection(nodeSelection);\n\n // You can also clear selection by setting it to `null`.\n $setSelection(null);\n});\n```\n\n## Focus\n\nYou may notice that when you issue an `editor.update` or\n`editor.dispatchCommand` then the editor can \"steal focus\" if there is\na selection and the editor is editable. This is because the Lexical\nselection is reconciled to the DOM selection during reconciliation,\nand the browser's focus follows its DOM selection.\n\nIf you want to make updates or dispatch commands to the editor without\nchanging the selection, can use the `SKIP_DOM_SELECTION_TAG` update tag\n(added in v0.22.0):\n\n```js\n// Call this from an editor.update or command listener\n$addUpdateTag(SKIP_DOM_SELECTION_TAG);\n```\n\nIf you want to add this tag during processing of a `dispatchCommand`,\nyou can wrap it in an `editor.update`:\n\n```js\n// NOTE: If you are already in a command listener or editor.update,\n// do *not* nest a second editor.update! Nested updates have\n// confusing semantics (dispatchCommand will re-use the\n// current update without nesting)\neditor.update(() => {\n $addUpdateTag(SKIP_DOM_SELECTION_TAG);\n editor.dispatchCommand(/* … */);\n});\n```\n\n`SKIP_DOM_SELECTION_TAG` does not apply to the initial editor state setup\n(the `$initialEditorState` property of the root extension, or\n`initialConfig.editorState` with the legacy `LexicalComposer`). On first mount the editor still scrolls\nto and focuses the initial selection. To prevent that, call\n`$setSelection(null)` inside your initial state setup function:\n\n```js\nconst editor = buildEditorFromExtensions({\n name: '[root]',\n // ...\n $initialEditorState: () => {\n // ... build your initial nodes ...\n $setSelection(null);\n },\n});\n```\n\nIf you have to support older versions of Lexical, you can mark the editor\nas not editable during the update or dispatch.\n\n```js\n// NOTE: This code should be *outside* of your update or command listener, e.g.\n// directly in the DOM event listener\nconst prevEditable = editor.isEditable();\neditor.setEditable(false);\neditor.update(\n () => {\n // run your update code or editor.dispatchCommand in here\n }, {\n onUpdate: () => {\n editor.setEditable(prevEditable);\n },\n },\n);\n```\n\n## Reading selection across a shadow boundary\n\nIf your plugin reads the DOM selection directly — through\n`Selection.anchorNode`, `Selection.getRangeAt(0)`, or similar — and the\neditor's `contentEditable` lives inside a `ShadowRoot`, the browser retargets\nthose reads to the shadow host. See\n[Shadow DOM and iframes](./shadow-dom.md) for the shadow-aware helpers\n(`getDOMSelectionPoints`, `getDOMSelectionRange`, etc.) that return the\nun-retargeted boundary points; they fall through to the standard reads in the\nplain light DOM, so there's nothing to do until you actually mount the editor\nin a shadow tree.\n\n### Selection change timing\n\n`SELECTION_CHANGE_COMMAND` runs **before reconciliation**, in a writable update,\nfor native, programmatic, and non-range selection changes. `$getSelection()`\nreturns the pending selection; `$getPreviousSelection()` returns the selection\nfrom the last committed state. A listener can normalize the selection or edit\nnodes before that same update commits. Listeners that change the selection may\ncause another notification before commit; they must converge.\n\nThis covers programmatic changes such as `node.select()`, which notify without\nwaiting for a DOM `selectionchange` event, and non-range selections such as\n`NodeSelection` and `TableSelection`, as well as native range selections.\n\nSelection listeners use the update's normal error handling. A throwing listener\nreports through `onError` and can abort the entire pending update, including the\nedit that triggered the notification and any other edits batched into that\ncommit, just like an explicit command dispatch inside that update. Because a\nprogrammatic selection change also notifies, a listener error can abort content\nedits made in the same update. Listener edits do not have a separate rollback\nscope.\n\nThe DOM is not guaranteed to match the pending state, even for a `NodeSelection`.\nNew nodes may not have an element yet, and DOM ranges, layout, and focus may\nstill reflect the previous state. Schedule DOM-dependent work after the update\nand read the reconciled state there:\n\n```ts\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n $onUpdate(() => {\n editor.read('latest', () => {\n // Read $getSelection(), look up elements, or position floating UI here.\n });\n });\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport `$onUpdate` and `COMMAND_PRIORITY_LOW` from `lexical`. Read selection and\nnodes inside the callback rather than capturing mutable pending objects.\n`registerUpdateListener` is another option for UI that must respond to every\ncommit, including content changes that do not change the selection. Updates\nusing `SKIP_DOM_SELECTION_TAG` still deliberately leave the browser selection\nunsynchronized.\n\n#### Update tags and local edits\n\nThe notification belongs to the pending update and inherits its tags. A listener\ncan inspect them with `$hasUpdateTag`. In particular, Yjs does not sync content\nedits back to peers when the update is tagged `COLLABORATION_TAG` or\n`HISTORIC_TAG`; history also treats `HISTORIC_TAG` as replaying an existing entry.\nThis applies to content edits made by selection listeners in those updates.\n\nListeners that only apply to local editing should skip those tagged updates. If\na remote change or undo must trigger an independent local content edit, schedule\nit after the tagged commit with `$onUpdate`, then start a fresh `editor.update`:\n\n```ts\nconst $applyLocalEdit = () => {\n // Read the current selection and nodes, then apply a convergent local edit.\n};\n\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n if ($hasUpdateTag(COLLABORATION_TAG) || $hasUpdateTag(HISTORIC_TAG)) {\n $onUpdate(() => editor.update($applyLocalEdit));\n } else {\n $applyLocalEdit();\n }\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport the tags and `$hasUpdateTag` from `lexical`. Re-read the state in the fresh\nupdate; it has its own collaboration and undo behavior. Calling `editor.update`\ndirectly inside the command listener queues a nested update that still belongs\nto the same tagged commit.\n\nAutomatic range and cleared-selection notifications require a connected editor\nroot. Changes committed while those notifications are skipped advance the\nselection baseline and are not replayed when the root reconnects. Non-range\nselections continue to notify in unmounted and headless editors,\nwith the same pre-reconciliation timing. Native dirty-selection notifications\nmay fire even when the selection compares equal to the previous selection.\n","isInternal":false,"tokens":2513,"sizeBytes":11388},{"name":"shadow-dom.md","path":"packages/lexical-website/docs/concepts/shadow-dom.md","rawUrl":"https://raw.githubusercontent.com/facebook/lexical/HEAD/packages/lexical-website/docs/concepts/shadow-dom.md","title":"Concepts Skill","category":"anthropic-skill","format":"markdown","content":"---\nsidebar_label: Shadow DOM and iframes\n---\n\n# Shadow DOM and iframes\n\nA Lexical editor works when its `contentEditable` lives inside an **open**\n[DOM `ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) (for\nexample inside a [web component](https://developer.mozilla.org/docs/Web/API/Web_components))\nor inside an `\n\n## Sharing one Yjs document between editors\n\nBy default a binding uses the `XmlText` shared type named `root` on the Yjs\n`Doc`, so each editor needs its own document. Two options let several editors\nlive in one document instead, which is what applications like collaborative\nsticky notes or comment threads usually want:\n\n- `rootName` picks a different top-level shared type, one per editor:\n\n```jsx\n\n```\n\n- `getXmlText` resolves the root yourself, for roots that are not top-level\n shared types (for example an `XmlText` stored in a `Y.Map`). It takes\n precedence over `rootName`:\n\n```jsx\nconst getXmlText = useCallback(\n (doc) => doc.getMap('notes').get(noteId),\n [noteId],\n);\n\n\n```\n\nGive each editor its own `id`, as above: the `id` keys the document map and the\nremote-cursor highlight registry, both of which are shared across the page, so\ntwo editors mounted under one `id` overwrite each other's entries.\n\nBoth options are also available on `createYjsBinding` for non-React usage.\n\n:::warning\n\nThe root is chosen when the binding is created, and a mounted editor cannot be\nrepointed at another root: changing `rootName` or `getXmlText` afterwards has no\neffect. To switch documents, remount the **editor** — put a `key` that changes\nwith the document on the component that owns the `LexicalComposer`. Remounting\nonly the plugin is not enough: the editor would keep the previous document's\ncontent and write it into the newly selected root.\n\n:::\n\n`getXmlText` runs while the binding is constructed, before the provider has\nsynced, so it has to resolve the root from whatever the local `Doc` holds at\nthat moment — reaching into a `Y.Array` that the server has not sent yet throws.\nEither mount the editor only once the note exists locally, or have the callback\ncreate the missing shared type. Write it to be idempotent: it can run more than\nonce for one editor (React StrictMode double-invokes render, and a remount\nbuilds a new binding), and a callback that unconditionally stores a new\n`XmlText` would throw away what the previous call stored.\n\nThe returned `XmlText` is checked to be an `XmlText` that is integrated into the\ndocument; that it is not already driving another live binding is yours to\nguarantee, since a second binding over one root takes over the collab nodes\ncached on its shared types.\n\nThe experimental `CollaborationPluginV2__EXPERIMENTAL` (and\n`createBindingV2__EXPERIMENTAL`) take the same two options, except that its\nroot is an `XmlElement`, so the callback is named `getXmlElement`. Create that\nelement as `new Y.XmlElement()` without a `nodeName`, which is how the root is\nrecognized.\n\n## Building collaborative plugins\n\n[Lexical Playground](https://playground.lexical.dev/) features set of the collaboration enabled plugins that integrate with primary document via `useCollaborationContext()` hook. Notable mentions:\n\n- [`CommentPlugin`](https://github.com/facebook/lexical/tree/main/packages/lexical-playground/src/plugins/CommentPlugin) - features use of the separate provider and Yjs room to sync comments.\n- [`ImageComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/ImageComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested caption editor.\n- [`PollOptionComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/PollComponent.tsx) - showcases poll implementation using `name` from the collaboration context.\n- [`StickyComponent`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/nodes/StickyComponent.tsx) - features use of the `LexicalExtensionEditorComposer` for its nested editor as well as sticky note position real-time sync.\n\n:::note\n\nWhile these \"playground\" plugins aren't production ready - they serve as a great example of collaborative Lexical capabilities as well as provide a good starting point.\n\n:::\n\n## Custom node property syncing\n\n`@lexical/yjs` syncs custom node properties by constructing a fresh node instance and inspecting its **own enumerable properties**. This means every property that should be synced across peers must be assigned in the constructor, even if the initial value is `undefined`.\n\n:::warning\n\nDeclaring a class property with TypeScript's optional syntax (`foo?: Type`) does **not** guarantee the property exists as an own enumerable property on the instance. Under TypeScript's default compilation settings (target < ES2022 without `useDefineForClassFields`), such declarations produce no initialization code.\n\n:::\n\n### What to do\n\nAlways initialize every node property in the constructor. Conditional initialization such as `if (someValue !== undefined) this.__someValue = someValue` is not enough, because the default construction path still needs to create the property.\n\nFor example:\n\n```ts\n// ✅ Correct — property is guaranteed to be an own property\nclass MyNode extends ElementNode {\n __someValue: string | undefined;\n\n constructor(someValue?: string, key?: NodeKey) {\n super(key);\n this.__someValue = someValue; // explicitly initialized\n }\n}\n\n// ❌ Incorrect — property may not exist as an own property\nclass MyNode extends ElementNode {\n __someValue?: string; // optional syntax without initialization\n\n constructor(key?: NodeKey) {\n super(key);\n // __someValue is never assigned → won't be synced via yjs\n }\n}\n```\n\nIf you use [`NodeState`](../concepts/node-state.md) for your custom properties, this concern does not apply. `NodeState` values are synced correctly without relying on constructor-created enumerable properties.\n\n## Yjs providers\n\nSetting up the communication between clients, managing awareness information, and storing shared data for offline usage is quite a hassle. Providers manage all that for you and are the perfect starting point for your collaborative app.\n\nSee [Yjs Website](https://docs.yjs.dev/ecosystem/connection-provider) for the list of the officially endorsed providers. Although it's not an exhaustive one.\n\n\n{\n \"label\": \"Concepts\",\n \"position\": 3\n}\n\n\n# Commands\n\nCommands are a very powerful feature of Lexical that lets you register listeners for events like `KEY_ENTER_COMMAND` or `KEY_TAB_COMMAND` and contextually react to them _wherever_ & _however_ you'd like.\n\nThis pattern is useful for building [`Toolbars`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) or complex extensions and nodes such as [tables](https://github.com/facebook/lexical/tree/main/packages/lexical-table) which require special handling for `selection`, `keyboard events`, and more.\n\nWhen registering a `command` you supply a `priority` and can return `true` to mark it as \"handled\", which stops other listeners from receiving the event. If a command isn't handled explicitly by you, it's likely handled by default in [`RichTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-rich-text/src/index.ts) or [`PlainTextExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-plain-text/src/index.ts).\n\n## `createCommand(...)`\n\nYou can view the core commands in the [`lexical` API reference](/docs/api/modules/lexical#commands). Other packages define their own, listed under Commands in each package's API reference, such as [`TOGGLE_LINK_COMMAND`](/docs/api/modules/lexical_link#toggle_link_command) in `@lexical/link`. If you need a custom command for your own use case, check out the typed `createCommand(...)` function.\n\n```js\nconst HELLO_WORLD_COMMAND: LexicalCommand = createCommand('HELLO_WORLD');\n\neditor.registerCommand(\n HELLO_WORLD_COMMAND,\n (payload: string) => {\n console.log(payload); // Hello World!\n return false;\n },\n COMMAND_PRIORITY_EDITOR,\n);\n\neditor.dispatchCommand(HELLO_WORLD_COMMAND, 'Hello World!');\n```\n\n## `editor.dispatchCommand(...)`\n\nCommands can be dispatched from anywhere you have access to the `editor` such as a Toolbar Button, an event listener, or an extension, but most of the core commands are dispatched from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\nCalling `dispatchCommand` will implicitly call `editor.update` to trigger its command listeners if it was not called from inside `editor.update`.\n\nDon't dispatch a command from inside a read-only context such as\n`editor.read(fn)` or `editorState.read(fn)`. Command listeners usually change\nthe editor, so Lexical runs them in a separate writable update and\ndevelopment builds log a warning when they detect this. Dispatch after the\nread returns instead.\n\n```js\neditor.dispatchCommand(command, payload);\n```\n\nThe `payload`s are typed via the `createCommand(...)` API, but they're usually a DOM `event` for commands dispatched from an event listener.\n\nHere are some real examples from [`LexicalEvents.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical/src/LexicalEvents.ts).\n\n```js\neditor.dispatchCommand(KEY_ARROW_LEFT_COMMAND, event);\n// ...\neditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic');\n```\n\nAnd another example from the [`ToolbarPlugin`](https://github.com/facebook/lexical/blob/main/packages/lexical-playground/src/plugins/ToolbarPlugin/index.tsx) in our Playground.\n\n```js\nconst formatBulletList = () => {\n editor.dispatchCommand(INSERT_UNORDERED_LIST_COMMAND);\n};\n```\n\nWhich is later handled by [`ListExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-list/src/LexicalListExtension.ts) to insert the list into the editor.\n\n```js\neditor.registerCommand(\n INSERT_UNORDERED_LIST_COMMAND,\n () => {\n $insertList('bullet');\n return true;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\n## `editor.registerCommand(...)`\n\nYou can register a command from anywhere you have access to the `editor` object, but it's important that you remember to clean up the listener with its remove listener callback when it's no longer needed.\n\nThe command listener will always be called from an `editor.update`, so you may use dollar functions. You should not use\n`editor.update` (and *never* call `editor.read(...)` or `editor.read('force-commit', ...)`) synchronously from within a command listener. It is safe to call\n`editor.read('latest', ...)` or `editor.getEditorState().read` if you need to read the previous state after updates have already been made.\n\n```js\nconst removeListener = editor.registerCommand(\n COMMAND,\n (payload) => boolean, // Return true to stop propagation.\n priority,\n);\n// ...\nremoveListener(); // Cleans up the listener.\n```\n\nThe easiest way to get clean-up right is to register commands from an\n[extension](/docs/extensions/defining-extensions)'s `register` function and\nreturn the remove callback. The editor calls it when it is disposed. To\nregister several things, combine their callbacks with `mergeRegister` from\n`@lexical/utils`.\n\n```js\nimport {LinkExtension, TOGGLE_LINK_COMMAND} from '@lexical/link';\nimport {COMMAND_PRIORITY_BEFORE_EDITOR, defineExtension} from 'lexical';\n\nexport const LinkLoggerExtension = defineExtension({\n // The command it observes is handled by LinkExtension\n dependencies: [LinkExtension],\n name: '@my-app/LinkLogger',\n register: (editor) =>\n editor.registerCommand(\n TOGGLE_LINK_COMMAND,\n (payload) => {\n console.log('link', payload);\n return false; // let the link extension handle it too\n },\n // LinkExtension handles this command at COMMAND_PRIORITY_EDITOR and\n // returns true, so observe it at the BEFORE variant of that priority.\n COMMAND_PRIORITY_BEFORE_EDITOR,\n ),\n});\n```\n\nA listener that only observes a command, like this one, needs to run before\nthe listener that handles it. Depending on the extension that handles it and\nusing the `COMMAND_PRIORITY_BEFORE_*` variant of its priority does that\nwithout escalating to a higher priority. See\n[Priorities and ordering](#priorities-and-ordering) below.\n\nIn a legacy React plugin, return the `registerCommand` call from a\n`useEffect` instead.\n\nAnd as seen above and below, `registerCommand`'s callback can return `true` to signal to the other listeners that the command has been handled and propagation will be stopped.\n\nHere's a simplified example of handling a `KEY_TAB_COMMAND` from [`TabIndentationExtension`](https://github.com/facebook/lexical/blob/main/packages/lexical-extension/src/TabIndentationExtension.ts), which is used to dispatch a `OUTDENT_CONTENT_COMMAND` or `INDENT_CONTENT_COMMAND`.\n\n```js\neditor.registerCommand(\n KEY_TAB_COMMAND,\n (payload) => {\n const event: KeyboardEvent = payload;\n event.preventDefault();\n return editor.dispatchCommand(\n event.shiftKey ? OUTDENT_CONTENT_COMMAND : INDENT_CONTENT_COMMAND,\n );\n },\n COMMAND_PRIORITY_EDITOR,\n);\n```\n\nNote that the same `KEY_TAB_COMMAND` command is registered by [`LexicalTableSelectionHelpers.ts`](https://github.com/facebook/lexical/blob/main/packages/lexical-table/src/LexicalTableSelectionHelpers.ts), which handles moving focus to the next or previous cell within a `TableNode`, but the priority is high (`COMMAND_PRIORITY_HIGH`) because this behavior is very important.\n\n### Priorities and ordering\n\nCommand listeners are called in the following order until a listener returns `true`:\n\n- From priority highest to lowest (critical, high, normal, low, editor)\n- All `COMMAND_PRIORITY_BEFORE_${priority}` listeners, most recently registered first\n- All `COMMAND_PRIORITY_${priority}` listeners, in registration order\n\n:::note\n\nThe `COMMAND_PRIORITY_BEFORE_*` priorities make it much easier to override\ndefault behavior without escalating the priority.\n\n:::\n\nIt is best practice to use the lowest priority possible, so most commands will\nbe registered with `COMMAND_PRIORITY_EDITOR` for the default behavior, then\ncommands to override that behavior can be registered with\n`COMMAND_PRIORITY_BEFORE_EDITOR`. The higher priorities mostly serve purposes\nsuch as being able to observe-but-not-handle events and to support legacy code\nthat predates the availability of `COMMAND_PRIORITY_BEFORE_*`.\n\nA modern lexical app will typically only need the\n`COMMAND_PRIORITY_BEFORE_EDITOR` priority since the\nlast-registered-called-first ordering is suitable for almost all use cases. The\nolder priorities without BEFORE can be considered legacy and are primarily\noffered for compatibility.\n\nHere is the full ordering of priorities, from lowest to highest:\n\n- `COMMAND_PRIORITY_EDITOR`\n- `COMMAND_PRIORITY_BEFORE_EDITOR`\n- `COMMAND_PRIORITY_LOW`\n- `COMMAND_PRIORITY_BEFORE_LOW`\n- `COMMAND_PRIORITY_NORMAL`\n- `COMMAND_PRIORITY_BEFORE_NORMAL`\n- `COMMAND_PRIORITY_HIGH`\n- `COMMAND_PRIORITY_BEFORE_HIGH`\n- `COMMAND_PRIORITY_CRITICAL`\n- `COMMAND_PRIORITY_BEFORE_CRITICAL`\n\n\n# Compared with ProseMirror\n\nLexical and [ProseMirror](https://prosemirror.net) are both frameworks for\nbuilding rich text editors on top of `contentEditable`, and both keep an\nimmutable document model as the source of truth. This page collects the main\ndifferences in one place, for readers who know one and are learning the other.\n\n## Document model {#document-model}\n\nLexical's tree is shaped like the HTML it renders (see\n[Document Model](./document-model.md)). This is a deliberate difference from\nProseMirror. ProseMirror's document is also a tree,\nand blocks can contain other blocks, but the inline content of a textblock is\na flat sequence of nodes (text and inline nodes) with marks for formatting and\nlinks, and every position in the document is a single integer.\n\n| | Lexical | ProseMirror |\n| -- | -- | -- |\n| Document | Immutable tree of nodes, one `RootNode` | Immutable tree of nodes, one `doc` node |\n| Node identity and navigation | Each node has a runtime key and knows its parent and siblings | Nodes are plain values with no parent links; a resolved position supplies ancestor context |\n| Blocks | `ElementNode` subclasses (paragraph, heading, list, table, …), or a block `DecoratorNode` (image, embed, …) | Block nodes defined in the schema |\n| Inline formatting | Format flags on each `TextNode` (bold, italic, code, …) | Marks on text |\n| Links and other inline wrappers | Inline `ElementNode`s (`LinkNode`, `MarkNode`) that contain text nodes | Marks on text, like formatting |\n| Embedded content | `DecoratorNode`, inline or block, rendered by your framework (for example React) | Leaf or atom nodes, often with a custom `NodeView` |\n| Several editable regions in one node | [Named slots](./named-slots.md): regions addressed by name, like a card's `title`, each isolated so editing and selection never cross the boundary | Child nodes in the order the schema's content expression allows, optionally marked `isolating`, or a separate editor inside a `NodeView` |\n| Addressing a position | Node key plus offset (`{key, offset, type}`) | One integer counted across the whole document |\n| Allowed structure | Declared by node classes, enforced with node transforms and normalization | Declared by a schema of content expressions |\n| Applying edits | Call node and selection methods inside `editor.update()` | Build a transaction from steps that address positions or ranges |\n| Rendering | Each node's `createDOM()`/`updateDOM()`, applied by the reconciler, and optionally changed per node class by a `DOMRenderExtension` override | `toDOM` in the schema, or a `NodeView` |\n\n## Serialization {#serialization}\n\nBecause a Lexical link is an element that already contains its text, it\nexports as an `` around those text nodes. A mark-based model has to find the\nadjacent text that shares a mark and group it into one element first.\n\n| Format | Lexical | ProseMirror |\n| -- | -- | -- |\n| JSON | `editorState.toJSON()`, restored with `editor.parseEditorState()` | `doc.toJSON()` and `Node.fromJSON(schema, json)` |\n| HTML export | `$generateHtmlFromNodes()`, using each node's `createDOM()` or `exportDOM()` | `DOMSerializer.fromSchema(schema)`, using `toDOM` from the schema's nodes and marks |\n| HTML import | `$generateNodesFromDOM()`, using `importDOM()` or `DOMImportExtension` rules | `DOMParser.fromSchema(schema)`, using the schema's `parseDOM` rules |\n| Markdown | `@lexical/markdown` transformers or `@lexical/mdast` | `prosemirror-markdown`: a markdown-it parser and a serializer with a function per node and mark |\n| Clipboard | Copy writes plain text, HTML, and Lexical JSON. Paste prefers the JSON, then HTML, then plain text. | Copy writes HTML and plain text. Paste parses the HTML with the schema's parse rules. |\n\nIn the JSON, a Lexical link is a `link` node with its text nodes as\n`children`, and bold is a `format` value on a `text` node, where\nProseMirror's JSON gives each text node a list of `marks`. In both editors the\ndefault HTML export reuses the definition that renders the editor\n(`createDOM()` in Lexical, `toDOM` in ProseMirror), so the two stay in step\nunless you override one. See [Serialization](../serialization/serialization.md)\nfor the details of each Lexical format.\n\n## History {#history}\n\nBoth editors group consecutive edits into one undo step. Lexical's\n[`HistoryExtension`](./history.md) merges edits made within `delay`\n(300ms by default) and keeps an unlimited stack unless you set `maxDepth`.\nProseMirror's history plugin uses `newGroupDelay: 500` and `depth: 100` by\ndefault, so `configExtension(HistoryExtension, {delay: 500, maxDepth: 100})`\nmatches its behavior.\n\n\n# Document Model\n\nAn [editor state](./editor-state.md) holds a tree of nodes. This page explains\nhow that tree is shaped.\n\n## A DOM-like tree\n\nLexical's node tree is shaped like the HTML it renders. A paragraph is an\n`ElementNode` whose children are the nodes inside it, and inline structure\nnests the same way: a link is a `LinkNode` element that contains the text\nnodes it wraps, just as an `` contains its text. Each node type decides how\nit renders with `createDOM()` and `updateDOM()`, so the model maps closely to\nthe DOM, and a position in the document is a node plus an offset within it.\n\nHere is a small document with a heading, a paragraph containing bold text and\na link, a block image, and a card that has a named `title` slot as well as\nordinary body children:\n\n```mermaid\nflowchart TB\n accTitle: The shape of a Lexical document tree\n accDescr: The root has four children in order: a heading, a paragraph, an image, and a card. The heading contains the text \"Welcome\". The paragraph contains the text \"Read the \", a bold text node \"docs\", and a link, which contains the text \"here\". The image is a block decorator node with no children. The card has a named slot called title, which holds a paragraph containing the text \"Card title\", and one ordinary child, a paragraph containing the text \"Card body\".\n root[\"Root\"] --> heading[\"Heading (h1)\"]\n root --> paragraph[\"Paragraph\"]\n root --> image[\"Image
(block DecoratorNode)\"]\n root --> card[\"Card
(ElementNode)\"]\n heading --> welcome[\"Text: 'Welcome'\"]\n paragraph --> read[\"Text: 'Read the '\"]\n paragraph --> docs[\"Text: 'docs'
{ format: bold }\"]\n paragraph --> link[\"Link\"]\n link --> here[\"Text: 'here'\"]\n card -.->|\"slot: title\"| titlePara[\"Paragraph\"]\n titlePara --> titleText[\"Text: 'Card title'\"]\n card --> body[\"Paragraph\"]\n body --> bodyText[\"Text: 'Card body'\"]\n```\n\nSolid arrows are ordinary children, which form an ordered list under their\nparent and are read with `getChildren()`. The dashed arrow is a\n[named slot](./named-slots.md): a separate channel on the host, keyed by name\ninstead of position and read with `$getSlot(card, 'title')`. A slot's value\nis the root of its own isolated region, so its `getParent()` is `null` and\n`$getSlotHost()` leads back to the card. Any `ElementNode` or `DecoratorNode`\ncan host slots, so a decorator such as the image could also expose an\neditable caption this way.\n\n## Working with the tree\n\nLexical code navigates the document the way DOM code does, with methods like\n`getParent()`, `getChildren()`, and `getNextSibling()`, and each node owns the\nDOM it renders. The resemblance is structural, not one\nnode per HTML element: bold or italic text, for example, is a format on a\n`TextNode`, not a separate `` or `` node. See\n[Nodes](./nodes.mdx) for the built-in node types.\n\n## Customizing rendering\n\nYou can also change how nodes render without subclassing them.\n[`DOMRenderExtension`](../serialization/dom-render.md) from `@lexical/html`\ntakes overrides for `createDOM`, `updateDOM`, and `exportDOM`, for one node\nclass or for every node, such as adding a `data-` attribute or wrapping a\nnode's children in another element. Each override calls `$next()` to get the\ndefault result and adjusts it, so overrides from several extensions compose.\nExport overrides only affect HTML export, and `createDOM` overrides also carry\nthrough to export for nodes that use the default `exportDOM`. Changes made\nwhile updating the editor's DOM don't; see\n[Lexical -> HTML](../serialization/serialization.md#lexical---html) for which\nhooks reach export.\n\nFor how the tree is converted to and from JSON, HTML, and Markdown, see\n[Serialization](../serialization/serialization.md#formats-at-a-glance). For\nhow this model differs from a mark-based editor, see\n[Compared with ProseMirror](./compared-with-prosemirror.md).\n\n\n# Working with DOM Events\n\nSometimes, when working with Lexical, it might be necessary or useful for you to attach a DOM Event Listener to the underlying DOM nodes that Lexical controls. For instance, you might want to show a popover when a user mouses over a specific node or open a modal when they click on a node. Either of these use cases (and many others) can be accomplished via native DOM Event Listeners. There are 3 main ways that you can listen for DOM Events on nodes controlled by Lexical:\n\n## 1. Event Delegation\n\nOne way to handle events inside the editor is to set a listener on the editor root element (the contentEditable Lexical attaches to). You can do this using a [Root Listener](listeners.md).\n\n```js\nfunction myListener(event) {\n // You may want to filter on the event target here\n // to only include clicks on certain types of DOM Nodes.\n alert('Nice!');\n}\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) => {\n if (rootElement === null) {\n return;\n }\n // add the listener to the current root element\n rootElement.addEventListener('click', myListener);\n // remove the listener when the root element changes - make sure the ref\n // to myListener is stable so the removal works and you avoid a memory leak.\n return () => rootElement.removeEventListener('click', myListener);\n }),\n});\n```\n\nAn extension's `register` returns a cleanup function, and the editor calls it\nwhen it is disposed, so there is no teardown to write by hand. Add\n`ClickExtension` to your editor's `dependencies` to use it.\nThis can be a simple, efficient way to handle some use cases, since it's not necessary to attach a listener to each DOM node individually.\n\nThe `addEventListener`/`removeEventListener` pairing above is common enough that the core `lexical` package exports a `registerEventListener(target, type, listener, options?)` helper. It attaches the listener and returns a dispose function that removes it, so the example above becomes:\n\n```js\nimport {defineExtension, registerEventListener} from 'lexical';\n\nconst ClickExtension = defineExtension({\n name: '@my-app/Click',\n register: (editor) =>\n editor.registerRootListener((rootElement) =>\n // registerEventListener returns the matching removeEventListener cleanup,\n // so there's no need to write the teardown by hand.\n rootElement === null\n ? undefined\n : registerEventListener(rootElement, 'click', myListener),\n ),\n});\n```\n\nIt mirrors the `addEventListener` overloads (so the event type is strongly typed) and composes well with `mergeRegister` when you need to register several listeners at once.\n\nTo attach several listeners to the same target, `registerEventListeners(target, listeners, options?)` takes a `{type: listener}` map and returns a single dispose function that removes all of them. Each listener's event argument is still strongly typed per event type, and the optional `options` argument is shared across every listener:\n\n```js\nimport {registerEventListeners} from 'lexical';\n\nconst removeListeners = registerEventListeners(\n rootElement,\n {\n click: onClick,\n keydown: onKeyDown, // receives a KeyboardEvent\n },\n {capture: true}, // shared by both listeners\n);\n```\n\nBecause `options` is shared, register a group that needs different options (such as a different `capture` flag) with a separate `registerEventListeners` call and combine the results with `mergeRegister`.\n\n## 2. Directly Attach Handlers\n\nIn some cases, it may be better to attach an event handler directly to the underlying DOM node of each specific node. With this approach, you generally don't need to filter the event target in the handler, which can make it a bit simpler. It will also guarantee that your handler isn't running for events that you don't care about. This approach is implemented via a [Mutation Listener](listeners.md).\n\n```js\nconst registeredElements: WeakSet = new WeakSet();\nconst removeMutationListener = editor.registerMutationListener(nodeType, (mutations) => {\n editor.getEditorState().read(() => {\n for (const [key, mutation] of mutations) {\n const element: null | HTMLElement = editor.getElementByKey(key);\n if (\n // Updated might be a move, so that might mean a new DOM element\n // is created. In this case, we need to add an event listener too.\n (mutation === 'created' || mutation === 'updated') &&\n element !== null &&\n !registeredElements.has(element)\n ) {\n registeredElements.add(element);\n element.addEventListener('click', (event: Event) => {\n alert('Nice!');\n });\n }\n }\n });\n});\n\n// teardown the listener - return it from an extension's `register` so the\n// editor removes it when it is disposed.\nremoveMutationListener();\n```\nNotice that here we don't worry about cleaning up, as Lexical will dereference the underlying DOM nodes and allow the JavaScript runtime garbage collector to clean up their listeners.\n\n## 3. Use NodeEventPlugin\n\nIf you're using React, we've wrapped approach #2 up into a simple React plugin that you can render inside your composer to achieve the same effect, without worrying about the details:\n\n```jsx\n\n {\n alert('Nice!');\n }}\n />\n\n```\n\nIf the editor lives inside a shadow root or an iframe, see\n[Shadow DOM and iframes](./shadow-dom.md) for the helper to read\n`event.target` through the shadow boundary — the browser retargets it to the\nshadow host on listeners attached above the boundary, so a plain\n`event.target` won't match a node inside the editor.\n\n\n# Editor State\n\n## Why is it necessary?\n\nWith Lexical, the source of truth is not the DOM, but rather an underlying state model\nthat Lexical maintains and associates with an editor instance.\n\nWhile HTML is great for storing rich text content it's often \"way too flexible\" when it comes to text editing.\nFor example the following lines of content will produce equal outcome:\n\n```html\nLexical\nLexical\nLexical\n```\n\n
\n See rendered version!\n
\n Lexical\n Lexical\n Lexical\n
\n
\n\nOf course, there are ways to normalize all these variants to a single canonical form, however this would require DOM manipulation and so re-rendering of the content. And to overcome this we can use Virtual DOM, or State.\n\nOn top of that it allows to decouple content structure from content formatting. Let's look at this example stored in HTML:\n\n```html\n

Why did the JavaScript developer go to the bar? Because he couldn't handle his Promises

\n```\n\n
\n \"Nested\n
Nested structure of the HTML state because of the formatting
\n
\n\nIn contrast, Lexical decouples structure from formatting by offsetting this information to attributes. This allows us to have canonical document structure regardless of the order in which different styles were applied.\n\nHere is the same content as a Lexical node tree, printed the way the\n[tree view](/docs/getting-started/devtools) shows it (the numbers are node keys):\n\n```text\nroot\n └ (2) paragraph\n ├ (3) text \"Why did the JavaScript developer go to the bar? \"\n ├ (4) text \"Because he couldn't handle his \" { format: bold }\n ├ (5) text \"Promise\" { format: bold, italic }\n └ (6) text \"s\" { format: bold }\n```\n\nThe paragraph's children are a flat list of text nodes, and the formatting is a\nproperty of each one, so there is only one way to represent this content.\n\n## Understanding the Editor State\n\nYou can get the latest editor state from an editor by calling `editor.getEditorState()`.\n\nEditor states have two phases:\n\n- During an update they can be thought of as \"mutable\". See \"Updating state\" below to\n mutate an editor state.\n- After an update, the editor state is then locked and deemed immutable from there on. This\n editor state can therefore be thought of as a \"snapshot\".\n\nEditor states contain two core things:\n\n- The editor node tree (starting from the root node). See\n [Document Model](./document-model.md) for how the tree is shaped.\n- The editor [selection](./selection.md) (which can be null).\n\nFor example, \"Hello world\" with a link around \"world\" and the caret at the\nend looks like this:\n\n```mermaid\nflowchart TB\n accTitle: A simple editor state\n accDescr: The root contains a paragraph with a \"Hello \" text node and a link. The link contains the \"world\" text node. The selection's anchor and focus both point to offset 5 in \"world\".\n subgraph state[\"EditorState\"]\n direction TB\n root[\"Root\"] --> paragraph[\"Paragraph\"]\n paragraph --> hello[\"Text: 'Hello '\"]\n paragraph --> link[\"Link\"]\n link --> world[\"Text: 'world'\"]\n selection[\"Selection\"] -.->|\"caret at offset 5\"| world\n end\n```\n\n`editor.getEditorState()` returns the latest committed state. Its `toJSON()`\nmethod serializes the document tree only; the selection and the runtime node\nkeys are not included. To restore saved content, pass the JSON to\n`editor.parseEditorState()` and the result to `editor.setEditorState()`. The\neditor must have the same node types registered. See\n[Serialization](../serialization/serialization.md) for JSON, HTML, and\nMarkdown.\n\nHere's an example of how you can initialize an editor with saved content and\nthen persist it. The saved JSON is passed as the editor's `$initialEditorState`:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\n// Get the saved content (e.g. loaded from a backend)\nconst initialEditorState = await loadContent();\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n);\neditor.setRootElement(document.getElementById('editor'));\n\n// Store the content (e.g. when the user submits a form)\nasync function onSubmit() {\n await saveContent(JSON.stringify(editor.getEditorState()));\n}\n```\n\nWith React, pass the extension to `LexicalExtensionComposer`. A component\nrendered inside it can reach the editor with `useLexicalComposerContext()`:\n\n```jsx\nimport {LexicalExtensionComposer} from '@lexical/react/LexicalExtensionComposer';\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\nimport {useMemo} from 'react';\n\nfunction SaveButton() {\n const [editor] = useLexicalComposerContext();\n return (\n saveContent(JSON.stringify(editor.getEditorState()))}>\n Save\n \n );\n}\n\nfunction Editor({initialEditorState}) {\n // The editor is recreated whenever this extension changes,\n // so keep it stable for the life of the editor.\n const extension = useMemo(\n () =>\n defineExtension({\n $initialEditorState: initialEditorState,\n dependencies: [RichTextExtension],\n name: '@my-app/editor',\n }),\n [initialEditorState],\n );\n return (\n \n \n \n );\n}\n```\n\n`$initialEditorState` is applied once, when the editor is built; changing it\nlater has no effect on that editor. See \"Updating state\" below for the proper\nway to change editor state after initialization.\n\n`$initialEditorState` accepts:\n\n- a JSON string or a parsed `SerializedEditorState` object, passed to\n `editor.parseEditorState()` (as in the example above);\n- an `EditorState` instance, applied directly with `editor.setEditorState()`;\n- a function `(editor) => void`, run inside `editor.update(...)`;\n- `null`, which skips default initialization entirely. Use this with\n [collaboration](/docs/collaboration/react) so that the Yjs document, not\n Lexical, owns the initial state.\n\nOmitting the field (or passing `undefined`) seeds the root with a default empty\n`ParagraphNode`. The two are not interchangeable: `null` leaves the root with no children,\nwhile `undefined` produces a single empty line. If your `loadContent` may yield `null` or\n`undefined` for new documents, coalesce to `undefined` (e.g. `(await loadContent()) ?? undefined`)\nso the editor still gets the default paragraph rather than the collab-style uninitialized\nstate.\n\nThe legacy `LexicalComposer` takes the same values as `initialConfig.editorState`,\nexcept that a function there only runs if the root is still empty.\n\n## Updating state\n\nAll reads and writes of the document happen inside a synchronous callback:\n\n```js\nimport {$createParagraphNode, $createTextNode, $getRoot} from 'lexical';\n\neditor.update(() => {\n const paragraph = $createParagraphNode();\n paragraph.append($createTextNode('Hello world'));\n $getRoot().append(paragraph);\n});\n\nconst text = editor.read('force-commit', () => $getRoot().getTextContent());\n```\n\n### The `$` function convention {#dollar-functions}\n\nFunctions whose names start with `$`, such as `$getRoot()` and\n`$getSelection()`, only work inside one of these callbacks, because they act\non the active editor state. Calling them anywhere else throws an error. The\nconvention is similar to React Hooks:\n\n| | React Hooks | Lexical `$` functions |\n| -- | -- | -- |\n| Naming | `useFunction` | `$function` |\n| Can only be called | while rendering a component | inside an update or read |\n| Can call others of the same kind | ✅ | ✅ |\n| Must be synchronous | ✅ | ✅ |\n| Must be called unconditionally, in the same order | ✅ | ❌ No such rule |\n\nCommand handlers and node transforms already run inside an update, so they\ncan call `$` functions directly.\n\nThis works because, while a callback runs, Lexical keeps the active editor and\nthe active editor state in module-level variables, and `$` functions read\nthem: `$getRoot()` returns the root of the active state, and `$getEditor()`\nreturns the active editor. Because the callback is synchronous, nothing else\ncan run in between and change them. The same mechanism enforces the\ndifference between reads and updates. Inside a read, a method that would\nchange a node throws `Cannot use method in read-only mode.`\n\nGive your own functions a `$` prefix when they call `$` functions, so it is\nclear where they can be used. The\n[`@lexical/rules-of-lexical`](/docs/packages/lexical-eslint-plugin) ESLint rule\nchecks this convention.\n\nThe same rule applies to node objects. Call node methods only inside a read or\nupdate. Every node has a key that identifies it across versions of the editor\nstate, and node methods use that key to find the latest version of the node.\nThis is why a node reference taken earlier in an update stays usable after the\nnode changes. Keys exist only at runtime: they are not serialized, and you\nshould treat them as opaque.\n\nBecause the callbacks are synchronous, do any asynchronous work (fetching\ndata, awaiting a promise) first, and then enter an update with the result.\n\nAvoid nesting one `editor.update()` inside another: the inner update does not\nrun immediately but is queued to run after the outer one. Never start an\nupdate inside a read.\n\nEach update works on a pending copy of the editor state, and updates made in\nthe same tick are committed and reconciled to the DOM together. See\n[Updates](./updates.mdx#update-lifecycle) for the full lifecycle.\n\n### Replacing the state\n\nAnother way to set state is `setEditorState` method, which replaces current state with the one passed as an argument.\n\nHere's an example of how you can set editor state from a stringified JSON:\n\n```js\nconst editorState = editor.parseEditorState(editorStateJSONString);\neditor.setEditorState(editorState);\n```\n\n:::warning\n\n`setEditorState` rejects an `EditorState` that satisfies `editorState.isEmpty()` — i.e.\nthe root is the only node and there is no selection. In a development build it throws\n`\"setEditorState: the editor state is empty. Ensure the editor state's root node never\nbecomes empty.\"`; in production it warns with the same message and recovers by appending\nan empty `ParagraphNode`, so the editor stays usable. The `EditorState` produced by\ninitializing with `editorState: null` and never appending content (typical for a\ncollaboration document before peers connect) has exactly this shape, so persisting and\nreloading such a state hits this path. Note that `parseEditorState` itself succeeds — the\ncheck lands on the apply step. To avoid relying on the recovery, guard with\n`editorState.isEmpty()` before calling `setEditorState`, or seed the document with a\n`ParagraphNode` before serializing.\n\n:::\n\n## Reading state\n\nWhich state you see depends on how you read it:\n\n- Inside `editor.update()` you see the **pending** state, where your changes\n are visible but transforms and reconciliation may not have run yet.\n `editor.read('pending', fn)` gives you the same view without allowing\n changes.\n- `editor.read('force-commit', fn)` first commits any pending updates, so it\n always sees a consistent, reconciled state. Do not call it inside an update.\n `editor.read(fn)` with no mode does the same thing, and is kept for\n convenience and backwards compatibility. Inside a mutation or update\n listener it does not commit an update that another listener started (that\n update commits after the listeners have run, so they observe commits in\n order); use `editor.read('latest', fn)` there.\n- `editor.read('latest', fn)` reads the most recently reconciled state without\n committing anything, so pending changes are not visible.\n- `editorState.read(fn, {editor})` reads one particular snapshot, such as the\n `editorState` an update listener receives. Passing the `editor` keeps\n `$getEditor()` and extension lookups working inside the callback.\n\n## State update listener\n\nIf you want to know when the editor updates so you can react to the changes, you can add an update\nlistener to the editor, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(\n () => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n },\n // Passing the editor keeps $getEditor() and extension lookups working.\n {editor},\n );\n});\n```\n\n## When are Listeners, Transforms, and Commands called?\n\nThere are several types of callbacks that can be registered with the editor that are related to\nupdates of the Editor State.\n\n| Callback Type | When It's Called |\n| -- | -- |\n| Update Listener | After reconciliation |\n| Mutation Listener | After reconciliation |\n| Node Transform | During `editor.update()`, after the callback finishes, if any instances of the node type they are registered for were updated |\n| Command | As soon as the command is dispatched to the editor (called from an implicit `editor.update()`) |\n\n## Synchronous reconciliation with discrete updates\n\nWhile commit scheduling and batching are normally what we want, they can sometimes get in the way.\n\nConsider this example: you're trying to manipulate an editor state in a server context and then persist it in a database.\n\n```js\neditor.update(() => {\n // manipulate the state...\n});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\nThis code will not work as expected, because the `saveToDatabase` call will happen before the state has been committed.\nThe state that will be saved will be the same one that existed before the update.\n\nFortunately, the `discrete` option for `LexicalEditor.update` forces an update to be immediately committed.\n\n```js\neditor.update(() => {\n // manipulate the state...\n}, {discrete: true});\n\nsaveToDatabase(editor.getEditorState().toJSON());\n```\n\n### Cloning state\n\nLexical state can be cloned, optionally with custom selection. One of the scenarios where you'd want to do it\nis setting editor's state but not forcing any selection:\n\n```js\n// Passing `null` as a selection value to prevent focusing the editor\neditor.setEditorState(editorState.clone(null));\n```\n\n\n# Running Without a Browser\n\nThe DOM is only needed to show an editor on screen. Because every read and\nupdate goes through the editor state, Lexical also works where there is no\nbrowser DOM:\n\n- **With no DOM at all.** An editor that has no root element skips\n reconciliation and DOM selection entirely, so you can build one with\n `buildEditorFromExtensions()` and never call `setRootElement()`. Adding\n `HeadlessExtension` from `@lexical/headless` makes that explicit: attaching a\n root element then throws, and nested editors are headless too. Updates,\n transforms, listeners, commands, and JSON serialization all still work,\n which is enough to process documents on a server, apply changes from a\n collaboration backend, or write tests.\n- **With a virtual DOM** such as happy-dom or jsdom, for the features that\n create DOM nodes, like HTML import and export. `withDOM()` from\n `@lexical/headless/dom` runs a callback with a temporary happy-dom window,\n for example to convert HTML on a server.\n\n## Example: converting saved JSON to HTML on a server\n\n```ts\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {HeadlessExtension} from '@lexical/headless';\nimport {withDOM} from '@lexical/headless/dom';\nimport {$generateHtmlFromNodes} from '@lexical/html';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [HeadlessExtension, RichTextExtension],\n name: '@my-app/server-editor',\n }),\n);\n\nexport function jsonToHtml(json: string): string {\n editor.setEditorState(editor.parseEditorState(json));\n return withDOM(() => editor.read(() => $generateHtmlFromNodes(editor)));\n}\n```\n\nThe editor must have the same node types registered as the editor that saved\nthe JSON, which is why it uses the same extensions. JSON and Markdown\nconversion do not need `withDOM()`.\n\n## `createHeadlessEditor()`\n\nBefore extensions, headless editors were created with `createHeadlessEditor()`\nfrom `@lexical/headless`. It still works, and it makes DOM-only methods such as\n`registerRootListener` and `registerMutationListener` throw. Because many\nextensions register those listeners, use `HeadlessExtension` with\n`buildEditorFromExtensions()` in new code.\n\n\n# History\n\nLexical adds support for Undo and Redo through the `@lexical/history` package —\n`registerHistory`, the `HistoryExtension` extension, or the `HistoryPlugin`\nReact component from `@lexical/react/LexicalHistoryPlugin`. Part of undo and redo requires supporting coalescing of certain dynamic operations such as continuous typing. The below provides background information regarding the continuous typing undo coalescing feature.\n\n**Undo Coalescing of Typed Text**\n\n**TL;DR**\nWhen working with text editors, users expect a well polished undo experience. A key part of this is a smooth, well thought out workflow when undoing continuous typing events. For this post, strict typing events may be limited to typing characters, backspacing and forward deleting. Users generally expect that continuous typing should fully undo with a single undo gesture and that they don’t require separate undo gestures for each character.\nThe algorithm that covers this is “undo coalescing of typed text” and there’s a certain degree of nuance involved. This post covers that nuance while attempting to avoid prescriptive implementation details.\n\n**What Kind of Edits Require Coalescing?**\nAs mentioned above, continuous typing should be coalesced into a single undo action. Continuous typing is a loaded phrase and we’ll get into some details below.\nThere are other types of edits that require undo coalescing such as rapidly resizing an image or rapidly changing the font size of selected text. These latter two examples fall under what might be termed “dynamic operations” and their implementation might vary quite a bit from coalescing of typing.\n\n**What Constitutes Continuous Typing?**\nFor the purposes of undo coalescing, continuous typing events are safely limited to these three actions:\n\n1. Forward typing characters (heads up, composed character typing discussed later).\n2. Deleting backwards, e.g. backspace gestures including backspace key presses.\n3. Forward deletion, e.g. forward delete gestures including Delete key presses.\n\nAny interruption to the above breaks the notion of continuous typing. Note that switching between either of these three actions may itself be considered an interruption of continuous typing or it may not. This ends up being a usability decision. In my opinion, when examining various word processors, switching between these three actions should maintain continuity, because users often make typos or corrections in the flow of typing and therefore would lean towards the whole sequence of typing, backspacing and deleting to be within a single undoable session.\nNote that Google Docs and Quip treat a switch between typing, backspacing and deleting as disruptions to the continuous typing sessions.\n\n**Start with Selected Text and Followup with Typing**\nLet’s start with some selected text. The user may have selected the text directly, as a result of pasting text or through some other sequence of steps. When followed by continuous typing, the initial selection should be included along with the following typing events as part of a single coalesced undo session.\n\n**Timeouts**\nText editing is generally a modeless user experience and so just about any event beyond the above typing actions will disrupt continuous typing. The first and foremost is a timeout.\nQuip seems to require continuous typing to occur within 1 second intervals, whereas Google Docs requires about 2 seconds. In my opinion, the timeout may stretch to as long as 3 to 5 seconds. The more time between typing events, the more chance the user has to intentionally input a block of text, a thought or concept.\nThe use of a timeout is not necessarily required, and the amount of time is certainly up for debate. Collaborative co-editing also makes use of timeouts when grouping text that is merged across clients. Longer timeouts tend to make collaboration a smoother, less disruptive experience, because receiving other client input while expressing one’s thoughts tends to be unhelpful.\nImplementers should consider the correct timeout based on their customer expectations and related collaborative features that might share this timeout.\n\n**Hard and Soft Returns**\nHard returns as generated by pressing the Return key tend to disrupt and thereby reset continuous typing.\nFor Google Docs and Quip, soft returns as generated by pressing shift+Return key do not terminate continuous typing. This makes sense in that the soft return ends text wrap but does not end the paragraph.\n\n**Changing Selections and Key Focus**\nAny change to the selection by the user should terminate coalescing. This includes:\n\n- Arrow gesture navigation.\n- Gestures to select a word, a sentence or a paragraph.\n- Any other selection change that does not move the blinking caret to the next or previous character by way of the above mentioned typing events.\n\nAdditionally, ending keyboard focus on the editing window, including moving focus to another editing window or a different view within the same window should also terminate coalescing. This also includes setting focus to modal popovers, such as, for example, a hyperlink property editor.\n\n**Composed Characters**\nCharacter composition occurs when typing diacritics, CJK and even emojis. The process usually involves at least these three phases:\n\n- Start composition.\n- Replace composed text with other text and remain composing. This step may occur many times within a single composition session.\n- Stop composition either through accepting the text or canceling the latest input.\n\nCoalescing should terminate at start composition. Replacing composed text should generally be coalesced. Stopping composition may or may not reset coalescing depending upon the implementation. Quip appears to try to coalesce multiple composed characters, but disrupts coalescing when switching between composed and non-composed characters. Google Docs appears to disrupt coalescing more frequently. Both coalesce the text replacements.\n\n**Auto Correct, Spelling Corrections and Text Substitutions**\nText substitution behaves much like composed characters. When the text is transformed, the coalescing should terminate and the transformed text becomes the first coalesced entry in the next undo session.\n\n**Copy & Pasting**\nAny actions like copy and paste typically trigger events that are not part of the 3 continuous typing actions described above. So, copy and paste also terminates coalescing.\n\n**In Conclusion**\nText undo coalescing greatly improves the usability of undo in that it allows the user to bypass all the intermediate events that went into forming or re-forming text within a paragraph. Given the modeless nature of text editing, limiting continuous typing to strictly three events allows for a robust and clean implementation. Implementers will need tight bottlenecks to trap selection changes, key focus changes as well as changes from collaborative clients. While the above is not complete by any means, I hope readers will find it helpful.\n\n## Tuning HistoryExtension for memory and long sessions\n\n`HistoryExtension` ships with config values chosen for the common case\nof a short-lived editor on a richly interactive surface. For\napplications that keep an editor mounted for a long time — chat\nthreads, long documents, anything where the user may produce thousands\nof distinct history events without reloading the page — two settings\nare worth tuning explicitly.\n\n### `maxDepth` — cap the undo stack\n\nBy default `maxDepth` is `null`, meaning the undo stack is\n**unbounded**. Every separate-history boundary (see \"What Constitutes\nContinuous Typing?\" above) pushes a `HistoryStateEntry` that retains a\nfull `EditorState` snapshot. Snapshots share a copy-on-write\n`NodeMap`, so the marginal cost of any one entry is small, but it is\nnot zero — and an unbounded stack accumulates a long tail over time.\n\nSet a finite `maxDepth` to keep the stack at a fixed length. The\nextension FIFO-evicts the oldest entries past the cap; older snapshots\nbecome unreachable and can be collected.\n\n```ts\nimport {configExtension, defineExtension} from 'lexical';\nimport {HistoryExtension} from '@lexical/history';\n\nconst editorExtension = defineExtension({\n // ...\n dependencies: [\n // 100 events is a reasonable starting point that supports a deep\n // enough undo stack for almost any interactive editing session.\n configExtension(HistoryExtension, {maxDepth: 100}),\n ],\n});\n```\n\nThe cap is also exposed as a writable signal on\n`HistoryExtension.output.maxDepth`, so it can be reconfigured at\nruntime (the new value applies to future pushes — the current stack\nis not retroactively trimmed when the cap is lowered).\n\n### `delay` — coalesce more aggressively\n\n`delay` is the merge window during which adjacent edits collapse into\nthe current history entry instead of pushing a new one. The default is\n`300`ms. A longer delay means fewer history events for the same\ntyping burst, which:\n\n- reduces the rate at which `undoStack` grows, multiplying the effect\n of any `maxDepth` cap, and\n- gives the user undo gestures that match larger semantic chunks of\n their writing.\n\nFor text-heavy editors a value in the `500`–`1000`ms range is common.\n\n```ts\nconfigExtension(HistoryExtension, {delay: 500, maxDepth: 100}),\n```\n\n### When NOT to cap history\n\nIf your editor is short-lived (mounted only for the duration of a\nmodal, page form, or single message draft) and undo is expected to\nreach back to the document's initial state, the default `maxDepth:\nnull` is fine — the stack will be discarded with the editor instance.\nThe cap matters when an editor is **long-lived** and can accumulate\nthousands of distinct history events without unmounting.\n\n\n# Key Management\n\nKeys are a fundamental concept in Lexical that enable efficient state management and node tracking. Understanding how keys work is crucial for building reliable editor implementations.\n\n## What are Keys?\n\nThe `__key` property is a unique identifier assigned to each node in the Lexical editor. These keys are:\n- Automatically generated by Lexical\n- Used to track nodes in the editor state\n- Essential for state management and updates\n- Immutable during a node's lifecycle\n\n## When to Use `__key`?\n\n### ✅ Correct Usage\n\nKeys should ONLY be used in two specific situations:\n\n1. **In Node Constructors**\n```typescript\nclass MyCustomNode extends ElementNode {\n constructor(someData: string, key?: NodeKey) {\n super(key); // Correctly passing key to parent constructor\n this.__someData = someData;\n }\n}\n```\n\n2. **In Static Clone Methods**\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### ❌ Incorrect Usage\n\nNever use keys in these situations:\n\n```typescript\n// ❌ Don't pass keys between different nodes\nconst newNode = new MyCustomNode(existingNode.__key);\n\n// ❌ Don't manipulate keys directly\nnode.__key = 'custom-key';\n```\n\n## How Lexical Uses Keys\n\n### Diagram\n\nThe dotted outlines show nodes that are re-used in a zero-copy fashion from one EditorState to the next\n\n```mermaid\ngraph TB\n subgraph s0[\"Initial State\"]\n direction TB\n m0[\"NodeMap (v0)\"]\n m0 -->|Key A| n0a[\"A (v0)\"]\n m0 -->|Key B| n0b[\"B (v0)\"]\n end\n subgraph s1[\"Create Node C\"]\n direction TB\n style n1a stroke-dasharray: 5 5\n style n1b stroke-dasharray: 5 5\n m1[\"NodeMap (v1)\"]\n m1 -->|Key A| n1a[\"A (v0)\"]\n m1 -->|Key B| n1b[\"B (v0)\"]\n m1 -->|Key C| n1c[\"C (v0)\"]\n end\n subgraph s2[\"Update Node A\"]\n direction TB\n style n2a stroke-dasharray: 5 0\n style n2b stroke-dasharray: 5 5\n style n2c stroke-dasharray: 5 5\n m2[\"NodeMap (v1)\"]\n m2 -->|Key A| n2a[\"A (v1)\"]\n m2 -->|Key B| n2b[\"B (v0)\"]\n m2 -->|Key C| n2c[\"C (v0)\"]\n end\n s0 -.-> s1 -.-> s2\n```\n\n### Node Map Structure\n\nThe EditorState maintains a `Map` that tracks all nodes. Nodes refer to each other using keys in their internal pointers:\n\n```typescript\n// Internal node structure (not for direct usage)\n{\n __prev: null | NodeKey,\n __next: null | NodeKey,\n __parent: null | NodeKey,\n // __first, __last and __size are only for ElementNode to track its children\n __first: null | NodeKey,\n __last: null | NodeKey,\n __size: number\n}\n```\n\nThese internal pointers maintain the tree structure and should never be manipulated directly.\n\n### Key-Related APIs\n\n1. **Editor Methods**\n ```typescript\n // Get node by key\n const node = $getNodeByKey(key);\n\n // Get the DOM element a node key is reconciled to\n const element = editor.getElementByKey(key);\n\n // Get latest version of a node\n const latest = node.getLatest();\n \n // Get mutable version for updates\n const mutable = node.getWritable();\n ```\n\n### Key Lifecycle\n\nNodeKeys are ephemeral and have several important characteristics:\n\n1. **Serialization**\n - Keys are never serialized\n - New keys are generated when deserializing (from JSON/HTML)\n - Keys are only meaningful within their EditorState instance\n\n2. **Uniqueness**\n - Keys are unique within an EditorState\n - Current implementation uses serial numbers for debugging\n - Should be treated as random and opaque values\n - Never logically reused\n\nKeys are used internally by Lexical to:\n1. Track nodes in the editor state\n2. Manage node updates and versions\n3. Maintain referential integrity\n4. Enable efficient state updates\n\n## Common Pitfalls\n\n1. **Key Reuse**\n ```typescript\n // ❌ Never do this\n function duplicateNode(node: LexicalNode) {\n return new SameNodeType(data, node.__key);\n }\n ```\n\n2. **Manual Key Assignment**\n ```typescript\n // ❌ Never do this\n node.__key = generateCustomKey();\n ```\n\n3. **Incorrect Constructor/Clone Implementation**\n ```typescript\n // ❌ Never do this - missing key in constructor\n class MyCustomNode extends ElementNode {\n constructor(someData: string) {\n super(); // Missing key parameter\n this.__someData = someData;\n }\n }\n\n // ✅ Correct implementation\n class MyCustomNode extends ElementNode {\n __someData: string;\n\n constructor(someData: string, key?: NodeKey) {\n super(key);\n this.__someData = someData;\n }\n \n static clone(node: MyCustomNode): MyCustomNode {\n return new MyCustomNode(node.__someData, node.__key);\n }\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__someData = prevNode.__someData;\n }\n }\n ```\n\n4. **Node Replacement**\n ```typescript\n // ❌ Never re-use the key when changing the node class\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(node.__key),\n withKlass: CustomNodeType\n }\n ]\n };\n\n // ✅ Correct: Use node replacement configuration\n const editorConfig = {\n nodes: [\n CustomNodeType,\n {\n replace: OriginalNodeType,\n with: (node: OriginalNodeType) => new CustomNodeType(),\n withKlass: CustomNodeType\n }\n ]\n };\n ```\n\n For proper node replacement, see the [Node Replacement guide](node-replacement.md).\n\n## Best Practices\n\n1. **Let Lexical Handle Keys**\n ```typescript\n import {$applyNodeReplacement} from 'lexical';\n\n // Create node helper function\n export function $createMyCustomNode(data: string): MyCustomNode {\n return $applyNodeReplacement(new MyCustomNode(data));\n }\n ```\n\n## Testing Considerations\n\nWhen writing tests involving node keys:\n\n```typescript\ntest('node creation', async () => {\n await editor.update(() => {\n // ✅ Correct: Create nodes normally\n const node = new MyCustomNode(\"test\");\n \n // ✅ Correct: Keys are automatically handled\n expect(node.__key).toBeDefined();\n expect(node.__key).not.toBe('');\n });\n});\n```\n\n## Performance Impact\n\nUnderstanding key management is crucial for performance:\n\n1. Keys enable efficient node lookup (O(1))\n2. Proper key usage prevents unnecessary re-renders\n3. Lexical's key system optimizes state updates\n4. Improper key manipulation can cause performance issues\n\n## Common Questions\n\n**Q: How do I reference a node later?**\nA: Store a reference to the node. Conventionally, all node methods will use `getLatest()` or `getWritable()` which will look up the latest version of that node before reading or writing its properties, which is equivalent to using the key but is type-safe (but may cause errors if you try to use a reference to a node that no longer exists). In some situations it may be preferable to use the key directly, which is also fine.\n\n**Q: How do I ensure unique nodes?**\nA: Let Lexical handle key generation and management. Focus on node content and structure.\n\n\n# Keyboard Accessibility\n\nLexical follows the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) keyboard model. This page documents the contracts that plugin authors and host applications rely on, so a Lexical editor can sit inside a larger keyboard-accessible flow without trapping or surprising the user.\n\n## Tab key\n\nBy default, `Tab` inside the editor follows the browser's normal focus order — it moves to the next focusable element on the page. There is no keyboard trap.\n\nThe optional `TabIndentationExtension` (`@lexical/extension`) takes over `Tab` and uses it for block indent / outdent. Hosts that mount this extension opt in to that behavior. WCAG 2.1.2 (No Keyboard Trap) still applies — pressing `Escape` blurs the editor (see below), at which point `Tab` leaves the editor again.\n\n## Escape key\n\nPressing `Escape` while the editor has focus calls `editor.blur()` via the rich-text Escape command handler (registered at `COMMAND_PRIORITY_EDITOR`). The handler only blurs when the current selection is a range selection; with a `NodeSelection` (or no selection) it returns `false` and falls through without blurring. After blur, the next `Tab` advances to the page's next focusable element — so the editor is not a hard keyboard trap. (`TabIndentationExtension` consumes `Tab` only while a range selection is active, and its own source notes that taking over `Tab` is generally discouraged for keyboard accessibility, so treat WCAG 2.1.2 conformance as something to verify in your integration rather than a guarantee.)\n\nPlugin authors who want to intercept `Escape` (modal close, dropdown close, etc.) should register their handler at a higher priority and return `true` to stop the command chain. Common patterns already established in the codebase:\n\n| Priority | Caller | Purpose |\n| --- | --- | --- |\n| `HIGH` | Floating link editor | Close the floating UI, keep editor focus |\n| `HIGH` | Equation component (while editing) | Close the equation editor input |\n| `NORMAL` | Comment plugin | Cancel inline comment editing |\n| `LOW` | Image component | Escape out of caption / resize editing: drop the inner selection and restore the `NodeSelection` on the image decorator |\n| `EDITOR` | Rich text (default) | `editor.blur()` (range selection only) |\n\nHandlers that return `false` let the chain continue, so Escape can still fall through to the default blur even after a higher-priority handler runs.\n\nSome host UI binds its close handler directly to a DOM `keydown` listener rather than going through `KEY_ESCAPE_COMMAND` — the playground's `Modal` via `window.addEventListener('keydown', ...)` and its `DropDown` via a React `onKeyDown` on the menu. Those paths run alongside the table above; they do not participate in the editor's command priority chain.\n\n## React hooks and `@lexical/a11y` extensions\n\nThe keyboard helpers below ship as `@lexical/a11y` _extensions_ — the extension is the API and does all of the work (event listeners, focus management, the live region). The `@lexical/react` hooks (`useLexicalFocusManagerRef`, `useLexicalRovingTabIndexRef`, `useLexicalFocusTrapRef`, `useLexicalAriaLiveRegion`) are thin React adapters that only _communicate_ with their extension: each returns a `RefCallback` (or an `announce` function) that drives the extension's signals. Using a hook therefore **requires** its matching extension to be registered in the editor's extension tree — it is not an optional integration path. Non-React hosts (Svelte, Vue, vanilla DOM) use the extensions directly and skip the hooks.\n\n## Toolbar focus jump\n\nThe playground uses `useLexicalFocusManagerRef` (`@lexical/react/useLexicalFocusManagerRef`) to provide a documented shortcut for moving focus from the editor to the toolbar without tabbing through the page. The hook returns a `RefCallback` that registers the attached element as a focus-managed toolbar. It listens for `Alt+F10` inside the editor and moves focus into the toolbar — preferring the item that currently carries `tabindex=\"0\"` (the active roving item, when paired with `useLexicalRovingTabIndexRef`), and otherwise the first focusable item. While focus is in the toolbar, pressing `Escape` restores both focus and the editor's prior selection via `editor.focus()`. Multiple toolbars can be registered simultaneously. Requires `FocusManagerExtension` from `@lexical/a11y` in the editor's extension tree.\n\nThis matches the WAI-ARIA editor menubar pattern and the convention used by Word and CKEditor. Hosts that don't mount `useLexicalFocusManagerRef` get the default browser flow (Tab in, Tab out).\n\n## Toolbar arrow-key navigation\n\nToolbars that opt into `useLexicalRovingTabIndexRef` (`@lexical/react/useLexicalRovingTabIndexRef`) collapse to a single tab stop: arrow keys move between items inside the toolbar; `Tab` moves past the toolbar as a whole. Items keep `tabindex=\"-1\"` except the active one (`tabindex=\"0\"`). The hook returns a `RefCallback` — multiple containers can be registered simultaneously. Tracks the WAI-ARIA toolbar pattern. Requires `RovingTabIndexExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Modal focus trap\n\n`useLexicalFocusTrapRef` (`@lexical/react/useLexicalFocusTrapRef`) returns a `RefCallback` that cycles `Tab` / `Shift+Tab` inside a modal container and restores focus to the previously-focused element on deactivation. While active, the trap also installs a document-level `focusin` listener that pulls any focus landing outside the container back to the first focusable descendant (or the container itself) — so it recovers from the browser routing `Tab` out to its own chrome. Although several containers can be _registered_, only one trap should be _active_ at a time: concurrent traps install competing `focusin` listeners and fight over focus. Escape is **not** intercepted by the hook — modal owners handle the close key themselves, so the editor's Escape contract above stays predictable. Requires `FocusTrapExtension` from `@lexical/a11y` in the editor's extension tree.\n\n## Screen reader announcements\n\n`useLexicalAriaLiveRegion` (`@lexical/react/useLexicalAriaLiveRegion`) returns a stable `announce(message)` function. The hook itself mounts no DOM — like the others above, it is a thin adapter that **requires `AriaLiveRegionExtension` from `@lexical/a11y` in the editor's extension tree**. That extension owns the lifecycle of the visually-hidden region (`role=\"status\"`, `aria-atomic`, `aria-live` defaulting to `polite` — configurable via its `politeness` config): the region is created in the extension's `register` step and disposed on the editor's teardown, not on the hook's unmount. `EditorModeAnnounceExtension` (mode transitions via `registerEditableListener`) and `HistoryAnnounceExtension` (undo / redo via `UNDO_COMMAND` / `REDO_COMMAND`) announce through the same region. Both extensions accept optional message overrides for i18n.\n\n## Component ARIA quick reference\n\nWhere Lexical already applies ARIA attributes today (set in each component's `createDOM` / `updateDOM`, declaratively in the surrounding React tree, or applied imperatively via `setAttribute` on a managed or portaled element — as the typeahead menu and the live region do):\n\n| Component | role | aria-\\* attributes |\n| --- | --- | --- |\n| `ToolbarPlugin` (playground) | `toolbar` | `aria-label` |\n| `Modal` (playground) | `dialog` | `aria-modal`, `aria-labelledby` |\n| `LexicalListItemNode` (check list leaf) | `checkbox` | `aria-checked` |\n| `LexicalMenu` typeahead popup | `listbox` | `aria-label` |\n| Editor root (while typeahead is open) | — | `aria-controls`, `aria-activedescendant` |\n| `EquationNode` (playground) | `math` | `aria-label` |\n| `useLexicalAriaLiveRegion` region | `status` | `aria-live`, `aria-atomic` |\n\nCustom nodes follow the same pattern: set the attributes in `createDOM` and re-apply in `updateDOM` when the state they reflect changes. There is no central ARIA contract on `LexicalNode`; treat each subclass's `createDOM` as the source of truth.\n\n## Browser notes\n\nLexical relies on the standard DOM `Escape` contract — verified on Chrome and Safari (macOS, normal window). Safari in fullscreen intercepts `Escape` at the browser level to exit fullscreen; that is the browser's contract, not Lexical's.\n\n## What this page does not cover\n\n- Touch / mobile screen reader gestures. The hooks above share the same DOM contracts with mobile (TalkBack, VoiceOver iOS) but mobile has not been exercised in this set of changes.\n- High contrast / forced-colors theming. See the playground's `index.css` `@media (forced-colors: active)` block for a baseline.\n\n\n# Listeners\n\nListeners are a mechanism that lets the Editor instance inform the user when a certain operation has occurred. All listeners follow a reactive pattern where you can do an operation upon something happening in the future. All listeners also return a function that easily allows for the\nlistener to be unregistered. Below are the different listeners that Lexical supports today:\n\n## `registerUpdateListener`\n\nGet notified when Lexical commits an update to the DOM.\n\n```js\nconst removeUpdateListener = editor.registerUpdateListener(({editorState}) => {\n // The latest EditorState can be found as `editorState`.\n // To read the contents of the EditorState, use the following API:\n\n editorState.read(() => {\n // Just like editor.update(), .read() expects a closure where you can use\n // the $ prefixed helper functions.\n });\n});\n\n// Do not forget to unregister the listener when no longer needed!\nremoveUpdateListener();\n```\n\nThe update listener callbacks receives a single argument containing the follow properties:\n\n- `editorState` the latest updated Editor State\n- `prevEditorState` the previous Editor State\n- `tags` a Set of all tags that were passed to the update\n- `dirtyElements` a Map of the NodeKeys of ElementNodes that were marked\n dirty, to a boolean that is true when the node was intentionally mutated\n- `dirtyLeaves` a Set of the NodeKeys of all dirty nodes that are not\n ElementNodes\n- `mutatedNodes` a Map of LexicalNode constructors to a\n `Map`, or null when no DOM was mutated. Only\n populated when at least one MutationListener is registered\n- `normalizedNodes` (advanced) the keys of TextNode descendants that were\n merged with a sibling by normalization\n\nOne thing to be aware of is \"waterfall\" updates. This is where you might schedule an update inside an update\nlistener, as shown below:\n\n```js\neditor.registerUpdateListener(({editorState}) => {\n // Read the editorState and maybe get some value.\n editorState.read(() => {\n // ...\n });\n\n // Then schedule another update.\n editor.update(() => {\n // ...\n });\n});\n```\n\nThe problem with this pattern is that it means we end up doing two DOM updates, when we likely could have\ndone it in a single DOM update. This can have an impact on performance, which is important in a text editor.\n\nA listener that re-enqueues work without a stop condition is worse than slow.\nThe editor keeps a cascade budget: once a run of updates re-enqueues more\nthan 100 times without yielding to the event loop, it discards the entire\npending update queue and warns. Bounded activity never reaches the limit —\nthe budget is reset from a macrotask, which a genuine runaway starves — but a\ntrue loop silently loses whatever else was queued.\n\nTo avoid this, we recommend looking into [Node Transforms](transforms.md), which allow you to listen to node changes and\ntransform them as part of the same given update, meaning no waterfalls!\n\n## `registerTextContentListener`\n\nGet notified when Lexical commits an update to the DOM and the text content of the editor changes from\nthe previous state of the editor. If the text content is the same between updates, no notifications to\nthe listeners will happen.\n\n```js\nconst removeTextContentListener = editor.registerTextContentListener(\n (textContent) => {\n // The latest text content of the editor!\n console.log(textContent);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveTextContentListener();\n```\n\n## `registerMutationListener`\n\nGet notified when a specific type of Lexical node has been mutated. There are three states of mutation:\n\n- `created`\n- `destroyed`\n- `updated`\n\nMutation listeners are great for tracking the lifecycle of specific types of node. They can be used to\nhandle external UI state and UI features relating to specific types of node.\n\nIf any existing nodes are in the DOM, and skipInitialization is not true, the listener\nwill be called immediately with an updateTag of 'registerMutationListener' where all\nnodes have the 'created' NodeMutation. This can be controlled with the skipInitialization option,\nwhich defaults to false.\n\n```js\nconst removeMutationListener = editor.registerMutationListener(\n MyCustomNode,\n (mutatedNodes, { updateTags, dirtyLeaves, prevEditorState }) => {\n // mutatedNodes is a Map where each key is the NodeKey, and the value is the state of mutation.\n for (let [nodeKey, mutation] of mutatedNodes) {\n console.log(nodeKey, mutation)\n }\n },\n {skipInitialization: false}\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveMutationListener();\n```\n\n## `registerEditableListener`\n\nGet notified when the editor's mode has changed. The editor's mode can be changed\nvia `editor.setEditable(boolean)`.\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (editable) => {\n // The editor's mode is passed in!\n console.log(editable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\n## `registerDecoratorListener`\n\nGet notified when the editor's decorator object changes. The decorator object contains\nall `DecoratorNode` keys -> their decorated value. This is primarily used with external\nUI frameworks.\n\n```js\nconst removeDecoratorListener = editor.registerDecoratorListener(\n (decorators) => {\n // The editor's decorators object is passed in!\n console.log(decorators);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveDecoratorListener();\n```\n\n## `registerRootListener`\n\nGet notified when the editor's root DOM element (the content editable Lexical attaches to) changes. This is primarily used to\nattach event listeners to the root element. *The root listener function is executed directly upon registration and then on any subsequent update.*\n\n```js\nconst removeRootListener = editor.registerRootListener(\n (rootElement, prevRootElement) => {\n //add listeners to the new root element\n //remove listeners from the old root element\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveRootListener();\n```\n\n\n# Named Slots\n\n:::warning\n\nNamed slots are experimental. The APIs described here are tagged\n`@experimental`, may change without a major version bump, and the\nserialization and collab formats should be treated as unstable until the\nfeature is stabilized.\n\n:::\n\nNamed slots let a single host node (an ElementNode or a DecoratorNode) own\nseveral isolated editable regions addressed by name — a Card's `title`, a\nPullQuote's `quote` and `attribution` — inside the host's own EditorState.\nEach region takes its own caret and formatting, never merges across the\nboundary, and `Cmd+A` doesn't spill into the rest of the document.\n\nBefore named slots, the usual answer was a nested editor per region: every\nregion lives in its own EditorState, so moving nodes between regions and\nkeeping history and collab in sync all require serialization and extra\n`editor.update` passes. The other node shapes don't fit either: plain\nElementNode children share one undivided linked list (Backspace at a region\nstart merges it into the previous region), and a DecoratorNode is atomic, so\nLexical can't own selection, collab, or serialization inside it. With named\nslots, editing a slot is just editing the one tree.\n\n:::note\n\nNamed slots are the model-level generalization of the rendering concept\nbehind [`$getDOMSlot`](/docs/api/modules/lexical#getdomslot) /\n`ElementDOMSlot` in the\n[DOM rendering](../serialization/dom-render.md) documentation. Every\nElementNode already has one _unnamed_ children channel, and `$getDOMSlot`\ncontrols where that channel's content attaches in the node's DOM. Named\nslots are additional, explicitly-named channels alongside it — symmetric in\nthat each renders into a controllable location in the host's DOM — but they\nalso carry the model-level semantics the unnamed channel doesn't: isolation\n(the virtual shadow root below), a separate NodeKey map, and their own\nserialization and collaboration.\n\n:::\n\n## The Model\n\nA host keeps a second child channel, a `Map` of slot name to NodeKey,\nseparate from its ordinary linked-list children. A slot value has its slot\nhost pointer set and `getParent() === null`, with exactly one of the two\nnon-null: `getParent()` stops at the slot boundary, and you climb out only\nthrough [`$getSlotHost()`](/docs/api/modules/lexical#getslothost).\n\nThe slot link itself acts as a **virtual invisible shadow root** between the\nhost and the value. Isolation is structural rather than a convention — an\naccidental boundary crossing surfaces as a thrown invariant, not silent\ncorruption.\n\nIn the DOM, each value renders synchronously into a keyless\n`
\">` container parked slots-first in the host\nDOM as a **hidden placeholder** (`display: none`), in a canonical order\nderived from the host class (see [slot order](#slot-order)). Nothing is\nvisible until the host explicitly attaches the container somewhere (see\n[Rendering](#rendering)) — mirroring how\n[`getDOMSlot`](/docs/api/modules/lexical#getdomslot) gives an element\ncontrol over where its linked-list children render.\n\n## Hosts and Values\n\nAny ElementNode or DecoratorNode can host slots. An ElementNode host can mix\nslots with ordinary children (a Card with a `title` slot plus regular body\nparagraphs); a DecoratorNode host has no children channel, so slots are its\nonly editable content (a PullQuote that is otherwise atomic).\n\nA slot value is any non-inline ElementNode or DecoratorNode. The value's\nshape decides the editing model:\n\n- **A bare block** (for example a ParagraphNode) behaves as a single-line\n field with no extra wrapper in the model, the JSON, or the DOM: its virtual\n scope holds exactly one block, so Enter is a no-op (hosts may map it to\n focus movement) and a multi-block paste flattens to inline content the way\n an `` sanitizes its value — line breaks stripped, block-only\n decorators dropped.\n- **A shadow-root container** (an ElementNode whose\n [`isShadowRoot()`](/docs/api/modules/lexical#isshadowroot) returns\n `true`) behaves as a multi-block region with normal block editing inside.\n\n## Declaring and Setting Slots\n\nA host class declares its slot names in [`$config()`](nodes.mdx); values are\nattached with [`$setSlot`](/docs/api/modules/lexical#setslot):\n\n```ts\nimport {\n $create,\n $createParagraphNode,\n $setSlot,\n ElementNode,\n} from 'lexical';\n\nclass CardNode extends ElementNode {\n $config() {\n return this.config('card', {extends: ElementNode, slots: ['title']});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n}\n\nfunction $createCardNode(): CardNode {\n const card = $create(CardNode);\n // Single-line title: the bare paragraph IS the slot value. An empty\n // paragraph is an empty field; to seed default text, append a non-empty\n // TextNode (empty TextNodes are eliminated during reconciliation).\n $setSlot(card, 'title', $createParagraphNode());\n // Ordinary body child, edited like any other block.\n return card.append($createParagraphNode());\n}\n```\n\nFor a multi-block region, use a shadow-root container as the value:\n\n```ts\nclass SlotContainerNode extends ElementNode {\n $config() {\n return this.config('slot-container', {extends: ElementNode});\n }\n createDOM(): HTMLElement {\n return document.createElement('div');\n }\n updateDOM(): boolean {\n return false;\n }\n isShadowRoot(): boolean {\n return true;\n }\n}\n\n$setSlot(\n pullQuote,\n 'quote',\n $create(SlotContainerNode).append(\n $createParagraphNode().append($createTextNode('First block')),\n $createParagraphNode().append($createTextNode('Second block')),\n ),\n);\n```\n\nThe core API surface (all exported from `lexical`):\n\n- [`$setSlot(host, name, node)`](/docs/api/modules/lexical#setslot) — place a value into a named slot, replacing\n any existing value under that name. Move semantics, mirroring `append`:\n the value is detached from any current parent or slot first. Throws if the\n value is inline or if the name is one of the reserved prototype keys\n (`__proto__`, `constructor`, `prototype`). Slotting a node into its own\n descendant would form a cycle; this is checked (and throws) in development\n only — in production it behaves like appending an ancestor through the\n children channel, which is likewise unguarded.\n- [`$getSlot(host, name)`](/docs/api/modules/lexical#getslot) — the value under a name, or `null`.\n- [`$getSlotNames(host)`](/docs/api/modules/lexical#getslotnames) — the host's slot names in canonical order.\n- [`$removeSlot(host, name)`](/docs/api/modules/lexical#removeslot) — detach the value under a name (the subtree is\n garbage-collected unless you reattach it elsewhere).\n- [`$getSlotHost(node)`](/docs/api/modules/lexical#getslothost) — the host a value is slotted into, or `null`.\n- [`$getSlotNameWithinHost(node)`](/docs/api/modules/lexical#getslotnamewithinhost) — the name of the slot\n a value occupies on its host (the reverse direction of `$getSlotHost`), or\n `null` when the node is not a slot value.\n- [`$getSlotFrame(node)`](/docs/api/modules/lexical#getslotframe) — the innermost slot value containing a node (the\n \"frame\" whose virtual shadow root scopes editing), or `null` when the node\n is not inside any slot.\n- [`$getSelectionSlotFrame(selection)`](/docs/api/modules/lexical#getselectionslotframe) — the slot frame a\n selection lives in, or `null` when it is outside any slot. Selection-driven\n exporters walk this frame instead of the root's children, because a\n selection inside a slot never contains its host and a root walk would\n export nothing. Works for every selection type, not just `RangeSelection`.\n- [`$isSlotHost(node)`](/docs/api/modules/lexical#isslothost) /\n [`$isSlotChild(node)`](/docs/api/modules/lexical#isslotchild) — type guards\n for the [`SlotHostNode`](/docs/api/modules/lexical#slothostnode) /\n [`SlotChildNode`](/docs/api/modules/lexical#slotchildnode) interfaces.\n\n## Slot Order\n\nSlot order is canonical and derived, never stored. Names declared in\n`$config()` (`slots: ['quote', 'attribution']`) sort first in declaration\norder; undeclared names sort after them, lexicographically by UTF-16 code\nunit (plain JavaScript string comparison, locale-independent). `$setSlot`\nre-canonicalizes on every write, so documents normalize on load and\nconcurrent collaborative additions converge to the same order on every\nclient. If presentation order matters, declare the names.\n\n## Rendering\n\nThe reconciler always renders every slot subtree synchronously, but into a\nhidden placeholder container — visibility is the host's explicit decision.\nThere are three ways to attach a slot, all sharing the same contract\n(attaching moves the container to the target, a no-op when it is already\nthere, and reveals it; the container renders as a normal block):\n\n1. **Synchronously in-lexical**: register a `$getSlotTargetElement`\n [`DOMRenderMatch`](/docs/api/modules/lexical_html#domrendermatch)\n override for the host's node class (a\n [DOM render override](../serialization/dom-render.md), not a node\n method — this is an advanced hook). The reconciler consults it whenever\n it creates or reconciles the slot's container and attaches/reveals\n within the same commit — no listener or framework hop. Returning\n `hostDom` reveals the slot in its default slots-first position:\n\n ```ts\n import {domOverride, DOMRenderExtension} from '@lexical/html';\n import {configExtension, defineExtension} from 'lexical';\n\n export const CardExtension = defineExtension({\n dependencies: [\n configExtension(DOMRenderExtension, {\n overrides: [\n domOverride([CardNode], {\n // Reveal the title in its default slots-first position within\n // the same commit that renders it. Returning an element from\n // deeper inside the host's DOM attaches it there instead;\n // $next() defers to lower-priority overrides (default: null,\n // a hidden placeholder).\n $getSlotTargetElement: (node, slotName, hostDom, $next, editor) =>\n hostDom,\n }),\n ],\n }),\n ],\n name: 'card',\n nodes: [CardNode],\n });\n ```\n\n2. **Imperatively**:\n [`mountSlotContainer(editor, nodeKey, slotName, target)`](/docs/api/modules/lexical#mountslotcontainer)\n and\n [`unmountSlotContainer(editor, nodeKey, container)`](/docs/api/modules/lexical#unmountslotcontainer)\n from `lexical` are the framework-independent primitives (e.g. from a\n [mutation listener](/docs/api/modules/lexical#registermutationlistener),\n which fires after the commit). `mountSlotContainer` resolves the container\n against the committed editor state\n ([`editor.getEditorState()`](/docs/api/modules/lexical#geteditorstate)), so\n the model it reads matches the reconciled DOM it reveals;\n `unmountSlotContainer` takes the container you already hold and only touches\n the DOM:\n\n ```ts\n import {mountSlotContainer} from 'lexical';\n\n // e.g. inside an extension's register(editor):\n const unregister = editor.registerMutationListener(\n CardNode,\n (mutations) => {\n for (const [nodeKey, mutation] of mutations) {\n if (mutation === 'destroyed') {\n continue;\n }\n const hostDom = editor.getElementByKey(nodeKey);\n if (hostDom !== null) {\n // Mounting in place: the placeholder is already parked in the\n // host DOM, so this just reveals it in its slots-first position.\n // Any element within the host's DOM works as a target.\n mountSlotContainer(editor, nodeKey, 'title', hostDom);\n }\n }\n },\n {skipInitialization: false},\n );\n ```\n\n `unmountSlotContainer(editor, nodeKey, container)` is the reverse: it\n hides the container and parks it back in the host DOM, for when a mount\n target goes away while the host remains.\n\n3. **From React chrome**: the\n [`useLexicalSlotRef`](/docs/api/modules/lexical_react_useLexicalSlotRef#uselexicalslotref)\n hook from `@lexical/react/useLexicalSlotRef` wraps the imperative pair and returns a\n ref that mounts a slot's container into your component — the usual choice\n for a DecoratorNode host's `decorate()` chrome (whose containers are\n opted back into `contentEditable` automatically, since the decorator DOM\n is non-editable):\n\n```tsx\nimport {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';\nimport {useLexicalSlotRef} from '@lexical/react/useLexicalSlotRef';\n\nfunction PullQuoteComponent({nodeKey}: {nodeKey: NodeKey}) {\n const [editor] = useLexicalComposerContext();\n const quoteRef = useLexicalSlotRef(editor, nodeKey, 'quote');\n const attributionRef = useLexicalSlotRef(\n editor,\n nodeKey,\n 'attribution',\n );\n return (\n
\n
\n
\n
\n );\n}\n```\n\nA `contentEditable=false` ElementNode shell can host React chrome the same\nway (slot containers opt into editing whenever the host DOM is\nnon-editable): the playground's Review demo portals chrome into the host DOM,\nattaches the author slot with `useLexicalSlotRef`, drives an interactive\nstar-rating widget that persists to NodeState, and applies the identical\nhidden-then-attach technique to its `getDOMSlot` children element. Such a shell should call\n[`setDOMUnmanaged(dom)`](/docs/api/modules/lexical#setdomunmanaged) in\n`createDOM` — the portal and the\nattach moves mutate the shell's children from outside the reconciler, and\nthe marker gives the shell the same mutation-observer exemption a\nDecoratorNode's DOM has.\n\n## Editable state\n\nA slot rendered inside a non-editable host (a DecoratorNode, or a\n`contentEditable=false` element shell) would not track the editor's editable\nstate on its own, so the reconciler gives its container an explicit\n`contentEditable` that follows `editor.isEditable()`, and re-renders the islands\nwhenever `setEditable` toggles — so a read-only editor's slots are not left\neditable. No extension is required. Slots always follow the editor; there is\ncurrently no way for a slot to override its own editable state.\n\nA host that attaches its own editable island which is *not* a slot container —\nfor example the Review demo's `getDOMSlot` children element inside its\n`contentEditable=false` shell — opts it into the same behavior with\n[`$markSlotEditable(element, editor)`](/docs/api/modules/lexical#marksloteditable),\nre-applying it from `updateDOM` so an editable toggle reaches the island.\n\n## Editing Behavior\n\n- **Selection never crosses a slot boundary.** Selections are clamped to the\n anchor's slot frame at every entry point (DOM resolution,\n [`$setSelection`](/docs/api/modules/lexical#setselection),\n and point mutation), so a mouse drag and a `shift+arrow` across the\n boundary land on the same clamped result. A focus in a slot of a host is\n moved past the whole host, or to the edge of the host's own children when\n the selection starts inside the host.\n- **Deletion stops at the boundary.** Backspace at the start of a slot and\n forward-Delete at its end are no-ops instead of merging across the virtual\n shadow root.\n- **`Cmd+A` scopes to the slot frame** when the caret is inside one; outside\n slots the default handlers keep the legacy whole-document behavior.\n Progressive expansion (block → enclosing slot frame → document on repeated\n presses) is provided by the opt-in\n [`SelectBlockExtension`](/docs/api/modules/lexical_extension#selectblockextension)\n from `@lexical/extension`.\n- **Generic block conversion skips slot values.** A slot value has no\n parent — its up-link is `$getSlotHost` — so selection-driven block\n converters (`$setBlocksType`, `$wrapNodes`, `$insertList` / `$removeList`,\n the markdown block shortcuts) treat it as ineligible and do nothing rather\n than replace it: the slot assignment is managed by the node or extension\n that owns the slot. Calling `LexicalNode.replace` directly on a slot value\n throws; reassign the slot with `$setSlot` on its host instead.\n- **Slots stay bound to their host through `replace`.** Replacing a slot\n *host* (`host.replace(other)`) does not transfer its slots to the\n replacement — slots are not necessarily portable across node types, so the\n slot map travels with the node, never with its position. If the replaced\n host is reattached in the same update (the\n [`$wrapNodeInElement`](/docs/api/modules/lexical_utils#wrapnodeinelement)\n pattern) it keeps its slots; if it stays detached, its slot subtrees are\n garbage-collected with it. The same applies to anything built on `replace`:\n converting a slot host with `$setBlocksType` produces a slot-less\n replacement block. Move a slot onto another host explicitly with\n `$setSlot`.\n- **A NodeSelection of an element carries its children.** Copy and export\n of a whole-host NodeSelection (e.g. a chrome click that selects \"the whole\n Card\") include the host's body children even though they aren't in the\n selection themselves — the old shell-only output made cut silently lossy.\n This applies only to NodeSelection; a partial RangeSelection over the host\n keeps per-child slicing.\n\n### Traversal is intentionally asymmetric\n\nContent reads include slot subtrees, slots-first:\n[`getTextContent()`](/docs/api/modules/lexical#gettextcontent),\n[`getAllTextNodes()`](/docs/api/modules/lexical#getalltextnodes),\nand the [`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots)\nfamily in `@lexical/utils` count slot content for search, copy, and\naccessibility. Navigation excludes them:\n[`getChildren()`](/docs/api/modules/lexical#getchildren),\n[`getFirstDescendant()`](/docs/api/modules/lexical#getfirstdescendant)\nand friends stay linked-list-only, so caret movement never walks into a slot\nby accident. Choose [`$dfs`](/docs/api/modules/lexical_utils#dfs) or\n[`$dfsWithSlots`](/docs/api/modules/lexical_utils#dfswithslots) depending on whether \"this subtree\" should mean the\nnavigable tree or all content.\n\n## Serialization\n\nJSON serialization is automatic in both directions. A host's slots serialize\nunder the reserved `$slots` key on\n[`SerializedLexicalNode`](/docs/api/modules/lexical#serializedlexicalnode)\n(a sibling of\nNodeState's reserved `'$'` key), keyed by slot name:\n\n```json\n{\n \"type\": \"card\",\n \"version\": 1,\n \"$slots\": {\n \"title\": {\"type\": \"paragraph\", \"children\": [], \"version\": 1}\n },\n \"children\": []\n}\n```\n\nParsing re-attaches each subtree with `$setSlot` and throws if `$slots`\nappears on a node that cannot host slots. The `$` prefix keeps the\nframework-owned key from colliding with a subclass that already serializes a\n`slots` property of its own.\n\nHTML serialization is opt-in per host, like NodeState: the exporter never\ndescends into slots on its own. A host's `exportDOM` can emit each slot into\na wrapper using\n[`$appendNodeToHTML`](/docs/api/modules/lexical_html#appendnodetohtml) from\n`@lexical/html`, and a\n[DOM import rule](../serialization/dom-import.md) on the host's\ndistinguishing markup maps the wrappers back through `$setSlot`.\n\n## Collaboration\n\nSlots sync on both the V1 and V2 Yjs bindings through a per-slot-diffed\n`Y.Map` stored under the reserved `__slots` attribute key on the host's shared\ntype (the channel reuses the host's `__slots` field name, which is already\nexcluded from the property sync). Hosts with declared slots create that map\neagerly, so two clients\nconcurrently setting *different* slot names for the first time merge\nper-entry instead of racing. Malformed or hostile remote entries are\nvalidated and skipped.\n\n:::caution\n\nPre-slots clients receiving slot data from upgraded peers will error rather\nthan render it. Enabling slots in long-lived shared documents should be\ngated on all participants running a slots-aware version; new clients\ntolerate unknown slot data going forward.\n\n:::\n\n## Reserved Names\n\nAdding slots reserves a few identifiers that custom node subclasses should\nnot define for their own purposes:\n\n- the `__slots` and `__slotHost` fields on ElementNode / DecoratorNode — the\n `__slots` name is also the collab attribute key for the slots channel, so it\n is reserved on the Yjs shared type too;\n- the `$slots` serialized JSON key.\n\n## Current Limitations\n\n- The caret / NodeCaret APIs throw across a slot boundary (\"no common\n ancestor\"); slot-aware caret traversal is a planned follow-up.\n- Nested slots (a slot whose host is itself slotted) are only handled one\n level deep by the runtime selection comparator.\n- The mixed-version collab caveat above.\n\n\n# Node Cloning\n\nUnderstanding how to properly clone and modify nodes is crucial for working with Lexical. This guide explains the different cloning mechanisms and when to use each one.\n\n## Types of Node Cloning\n\nLexical provides several ways to clone nodes, each serving a different purpose:\n\n1. `static clone()` - Internal API for state management\n2. `$copyNode()` - Public API for creating new nodes\n3. `getWritable()` - Public API for node modifications\n\n## The `clone` Method\n\n### What is `clone`?\n\nThe `clone` method is a static method that creates the next version of a node. A node that declares [`$config()`](./nodes.mdx) has one synthesized for it and need not implement it — a hand-written `clone` is only required for a node that does not use `$config()`, or whose constructor has required arguments. Either way, it's important to understand that this is an **internal API** used by Lexical's state management system.\n\n```typescript\nclass MyCustomNode extends ElementNode {\n static clone(node: MyCustomNode): MyCustomNode {\n // ✅ Correct implementation\n return new MyCustomNode(node.__someData, node.__key);\n }\n}\n```\n\n### When is `clone` Used?\n\n1. **Internal State Management**\n - Used by Lexical internally\n - Part of the editor's state update system\n - Called by `getWritable()`\n\n2. **Node Mutations**\n ```typescript\n // Example of a node method implementation\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n }\n\n node.setData(\"new data\");\n ```\n\n### When NOT to Use `clone`?\n\n```typescript\n// ❌ Never do this\nfunction $duplicateNode(node: MyCustomNode) {\n return MyCustomNode.clone(node); // Don't call clone directly\n}\n```\n\n## The `afterCloneFrom` Method\n\n### What is `afterCloneFrom`?\n\n`afterCloneFrom(prevNode)` runs on every clone, right after it is constructed,\nand copies over whatever the constructor did not. The base implementation\ncarries the node's links to its parent and siblings and its\n[NodeState](./node-state.md), and `ElementNode` and `TextNode` carry their own\nbuilt-in properties such as format, style, and indent. A property that is\ncopied neither by the constructor nor by some `afterCloneFrom` silently\nreverts to its default on the node's next write.\n\n### When you don't need it\n\nWith the modern APIs you usually don't write one at all:\n\n- **Serialization schema.** A property declared as a field in a `$config`\n [`json` schema](./nodes.mdx#creating-custom-nodes-with-a-serialization-schema)\n (`withField(stringValue(), {field: '__label'})`) is carried across the\n clone for you, because the schema says where it is stored. Available in\n Lexical v0.51.0 and later.\n- **NodeState.** State created with `createState` and stored with `$setState`\n is carried by the base `afterCloneFrom`, so a node whose extra data lives\n only in NodeState needs nothing.\n\n```ts\n// At module scope, above the class, so TypeScript checks it against the class\nconst calloutSchema = nodeSchema()({\n label: withField(stringValue(), {field: '__label'}),\n});\n\nclass CalloutNode extends ElementNode {\n __label: string = '';\n\n // No afterCloneFrom: `__label` is declared as a field in calloutSchema, so\n // it is carried across every clone.\n $config() {\n return this.config('callout', {extends: ElementNode, json: calloutSchema});\n }\n}\n```\n\n### When you still need it\n\nOverride `afterCloneFrom` for a property that neither of those covers: a\nfield that isn't in the node's schema, one declared only through accessor\nmethods (see\n[Carrying properties across a clone](../serialization/serialization.md#carrying-properties-across-a-clone)),\nor any property of a node written without a schema. Always call\n`super.afterCloneFrom(prevNode)` first so the inherited properties and\nNodeState are still carried:\n\n```ts\nclass MyCustomNode extends ElementNode {\n __data: string = '';\n\n afterCloneFrom(prevNode: this): void {\n super.afterCloneFrom(prevNode);\n this.__data = prevNode.__data;\n }\n}\n```\n\nLike `clone`, `afterCloneFrom` is called by Lexical; don't call it yourself\nexcept through `super`.\n\n## Using `$copyNode`\n\n### What is `$copyNode`?\n\n`$copyNode` is the public API for creating a copy of a node with a new key. Use this when you need to create a duplicate node.\nBy default, all properties and `NodeState` will be copied to the new node, and then `resetOnCopyNodeFrom` will be called to\nallow the node to optionally reset certain properties (and NodeState configured with `resetOnCopyNode: true`) to defaults\n(such as the checked state of a `ListItemNode`).\n\n```typescript\n// ✅ Correct: Using $copyNode\nconst copy = $copyNode(existingNode);\n```\n\n### When to Use `$copyNode`?\n\n1. **Creating Duplicates**\n ```typescript\n // ✅ Correct: Duplicating a node\n const duplicate = $copyNode(originalNode);\n someParent.append(duplicate);\n ```\n\n## Using `getWritable`\n\n### What is `getWritable`?\n\n`getWritable` is an internal API used within node method implementations to get a mutable version of a node. Node consumers should use the node's public methods instead.\n\n```typescript\n// ✅ Correct: Implementation of a node method\nclass MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data;\n return self;\n }\n}\n\n// ✅ Correct: Using the node\nconst node = new MyCustomNode();\nnode.setData(\"new value\");\n```\n\n## Common Patterns\n\n### Modifying Nodes\n\n```typescript\n// ✅ Correct: Modifying a node\nfunction $updateNodeData(node: MyCustomNode, newData: string): MyCustomNode {\n return node.setData(newData);\n}\n\n// ❌ Incorrect: Don't clone manually\nfunction $updateNodeDataWrong(node: MyCustomNode, newData: string): MyCustomNode {\n const clone = MyCustomNode.clone(node);\n clone.setData(newData);\n return clone;\n}\n```\n\n### Copying Nodes\n\n```typescript\n// ✅ Correct: Copying a node\nfunction $duplicateNode(node: MyCustomNode): MyCustomNode {\n return $copyNode(node);\n}\n\n// ❌ Incorrect: Don't use clone\nfunction $duplicateNodeWrong(node: MyCustomNode): MyCustomNode {\n return node.constructor.clone(node);\n}\n```\n\n## Performance Considerations\n\n1. **Referential Integrity**\n - `getWritable()` ensures proper EditorState updates with new clones\n - Prevents \"orphaned\" nodes that won't be rendered\n\n2. **State Management**\n ```typescript\n class MyCustomNode extends ElementNode {\n setData(data: string): this {\n const self = this.getWritable();\n self.__data = data; // Properly tracked by editor\n return self;\n }\n }\n ```\n\n## Testing\n\n```typescript\ntest('node modification', async () => {\n await editor.update(() => {\n const node = new MyCustomNode(\"test\");\n \n node.setData(\"new data\");\n \n // ✅ Correct: Use $copyNode for duplication\n const copy = $copyNode(node);\n });\n});\n```\n\n## Related Concepts\n\n- [Editor State](editor-state.md) - How cloning affects editor state\n- [Nodes](nodes.mdx) - Core concepts about Lexical nodes\n\n## Common Questions\n\n**Q: How do I duplicate a node?**\nA: Use `$copyNode(node)` to create a new copy with a new key.\n\n**Q: When should I use clone?**\nA: Never directly. Use `$copyNode()` or `getWritable()` instead.\n\n\n# Node Replacement\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a subclass.\n\n## Use Case\n\n:::note\n\nIn earlier versions of this documentation, \"Node Replacement\" was called \"Node Overrides\".\nWe've changed the name to match the terms used in the implementation.\n\n:::\n\n:::tip\n\nIf your use case only requires adding ad-hoc data to existing nodes, you may be able to use the [NodeState](node-state.md) API instead of subclassing and node replacement.\n\n:::\n\nSome of the most commonly used Lexical Nodes are owned and maintained by the core library. For example, ParagraphNode, HeadingNode, QuoteNode, List(Item)Node etc - these are all provided by Lexical packages, which provides an easier out-of-the-box experience for some editor features, but makes it difficult to override their behavior. For instance, if you wanted to change the behavior of ListNode, you would typically extend the class and override the methods. However, how would you tell Lexical to use *your* ListNode subclass in `ListExtension` instead of using the core ListNode? That's where Node Replacement can help.\n\n\nNode Replacement allow you to replace all instances of a given node in your editor with instances of a different node class. This can be done through the `nodes` of an extension:\n\n```ts\nconst CustomParagraphExtension = defineExtension({\n name: '@my-app/CustomParagraph',\n nodes: () => [\n // Don't forget to register your custom node separately!\n CustomParagraphNode,\n {\n replace: ParagraphNode,\n with: (node: ParagraphNode) => {\n return $createCustomParagraphNode();\n },\n withKlass: CustomParagraphNode,\n },\n ],\n});\n```\nIn the snippet above,\n- `replace`: Specifies the core node type to be replaced. \n- `with`: Defines a transformation function to replace instances of the original node to the custom node. \n- `withKlass`: This option ensures that behaviors associated with the original node type work seamlessly with the replacement. For instance, node transforms or mutation listeners targeting ParagraphNode will also apply to CustomParagraphNode when withKlass is specified. Without this option, the custom node might not fully integrate with the editor's built-in features, leading to unexpected behavior.\n\nOnce this is done, Lexical will replace all ParagraphNode instances with CustomParagraphNode instances. One important use case for this feature is overriding the serialization behavior of core nodes. Check out the full example below.\n\n## Node Replacement Example\n\nThis example demonstrates using Node Replacement to replace all `ParagraphNode` with a `CustomParagraphNode` that overrides `createDOM`.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-replacement?file=src/main.tsx)\n\n\n\n\n# NodeState\n\nThe NodeState API introduced in v0.26.0 allows arbitrary state to be added\nad-hoc to any node in a way that participates with reconciliation, history,\nand JSON serialization.\n\n## Use Case\n\nNodeState allows your application to define keys that can be stored on\nany node with automatic JSON support.\n\n:::tip\n\nYou can even add node state to the RootNode to store document-level metadata.\n\n:::\n\nWith a combination of NodeState and other APIs such as\n[Listeners](listeners.md) or\n[Transforms](transforms.md) you can\nlikely shape the editor to meet your needs without having to do much\n[Node Customization](node-replacement.md).\n\nEven when you are subclassing nodes, using NodeState instead of additional\nproperties to store the node's data can be [more efficient](#efficiency)\nand will save you from writing a lot of boilerplate in the constructor,\nupdateFromJSON, and exportJSON.\n\n## Usage\n\n### createState\n\n[createState](/docs/api/modules/lexical#createstate)\ncreates a\n[StateConfig](/docs/api/modules/lexical#stateconfig)\nwhich defines the key and configuration for your NodeState value.\n\nThe key must be locally unique, two distinct StateConfig must not have the\nsame string key if they are to be used on the same node.\n\nTypical usage will look something like this:\n\n```ts\nconst questionState = createState('question', {\n parse: (v) => (typeof v === 'string' ? v : ''),\n});\n```\n\nThe required `parse` function serves two purposes:\n- It provides a type-safe and runtime-safe way to parse values that were\n serialized to JSON\n- When called with `undefined` (or any invalid value) it should return some\n default value (which may be `undefined` or `null` or any other value you\n choose)\n\nIn this case, the question must be a string, and the default is an\nempty string.\n\nSee the\n[createState](/docs/api/modules/lexical#createstate)\nAPI documentation for more details, there are other optional settings\nthat you may want to define particularly if the value is not a primitive\nvalue such as boolean, string, number, null, or undefined.\n\n:::tip\n\nInstead of writing parse functions by hand, use the\n[serialization schema combinators](/docs/serialization/#declarative-serialization-schemas-with-config)\nfrom `lexical`, such as `stringValue`, `numberValue`, `enumValue`,\n`arrayValue`, `objectValue`, and `nullable`. They are the same ones a node's\n`$config` JSON schema uses. A schema is itself a parse function, so it can be\npassed directly as `parse`:\n\n```ts\nimport {arrayValue, createState, stringValue} from 'lexical';\n\nconst questionState = createState('question', {parse: stringValue()});\nconst tagsState = createState('tags', {parse: arrayValue(stringValue())});\n```\n\nBecause `parse` is just a function, the combinators also compose with schema\nlibraries such as [zod](https://zod.dev/), [ArkType](https://arktype.io/),\n[Effect](https://effect.website/), and [Valibot](https://valibot.dev/). Wrap a\nlibrary's validator in a parse function that returns a default for invalid\ninput, or use `transformValue` to refine what a combinator parsed.\n\n:::\n\n### $getState\n\n[$getState](/docs/api/modules/lexical#getstate) gets the\nNodeState value from the given node, or the default if that key was never\nset on the node.\n\n```ts\nconst question = $getState(pollNode, questionState);\n```\n\nSee also\n[$getStateChange](/docs/api/modules/lexical#getstatechange)\nif you need an efficient way to determine if the state has changed on two\nversions of the same node (typically used in updateDOM, but may be useful in\nan update listener or mutation listener).\n\n### $setState\n\n[$setState](/docs/api/modules/lexical#setstate) sets the\nNodeState value on the given node.\n\n```ts\nconst question = $setState(\n pollNode,\n questionState,\n 'Are you planning to use NodeState?',\n);\n```\n\n:::tip\n\nThe last argument is a ValueOrUpdater, just like with React's useState\nsetters. If you use an updater function and the value does not change,\nthe node and its NodeState *won't* be marked dirty.\n\n:::\n\n## Serialization\n\nThe NodeState for a node, if any values are set to non-default values, is\nserialized to a record under a single\n[NODE_STATE_KEY](/docs/api/modules/lexical#node_state_key)\nwhich is equal to `'$'`.\n\n```json\n{\n \"type\": \"poll\",\n \"$\": {\n \"question\": \"Are you planning to use NodeState?\"\n }\n}\n```\n\n:::tip\n\nBy default, it is assumed that your parsed values are JSON serializable,\nbut for advanced use cases you may use values such as Date, Map, or Set\nthat need to be transformed before JSON serialization. See the\n[StateValueConfig](/docs/api/modules/lexical#statevalueconfig)\nAPI documentation.\n\n:::\n\n### Flat serialization with `$config`\n\nNodes that declare a `StateConfig` in [`$config`](nodes.mdx#creating-custom-nodes-with-config-and-nodestate)\nwith `flat: true` lift that key to the top level of the serialized node\ninstead of nesting it under `'$'`. This makes the JSON shape identical\nto a legacy node that stored the value as a `__property` instance\nvariable, so existing payloads continue to round-trip after the node is\nmigrated to NodeState.\n\nFor example, a `ColoredNode` that extends `TextNode` and declares a flat\n`color` state (see [Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\n$config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n}\n```\n\nserializes as:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"color\": \"red\"\n}\n```\n\nA non-flat (default) state on the same node would instead appear under\n`'$'`:\n\n```json\n{\n \"type\": \"colored\",\n \"text\": \"hello\",\n \"$\": {\n \"color\": \"red\"\n }\n}\n```\n\nIn both cases, a key is only emitted when the current value is not equal\nto the default returned by its `parse` function — see\n[Efficiency](#efficiency).\n\n:::note\n\nDon't reuse a flat key that a superclass already serializes (e.g. `text`\non `TextNode`).\n\n:::\n\n### Upgrading a legacy JSON property to NodeState\n\nA node that stores data as a `__property` instance variable with custom\n`exportJSON`/`importJSON`/`updateFromJSON` can be migrated to NodeState\nwith `flat: true` without changing its serialized JSON shape.\n\nBefore — `ColoredNode` with a `__color` property and hand-written\nserialization (see the full legacy example in\n[Extending TextNode with `$config`](nodes.mdx#extending-textnode-with-config)):\n\n```ts\nexport type SerializedColoredNode = Spread<\n {color?: string},\n SerializedTextNode\n>;\n\nexport class ColoredNode extends TextNode {\n __color: string;\n\n constructor(text: string = '', color: string = DEFAULT_COLOR, key?: NodeKey) {\n super(text, key);\n this.__color = color;\n }\n\n static getType(): string {\n return 'colored';\n }\n\n static clone(node: ColoredNode): ColoredNode {\n return new ColoredNode(node.__text, node.__color, node.__key);\n }\n\n static importJSON(serializedNode: SerializedColoredNode) {\n return new ColoredNode().updateFromJSON(serializedNode);\n }\n\n updateFromJSON(serializedNode: SerializedColoredNode) {\n const self = super.updateFromJSON(serializedNode);\n self.__color =\n typeof serializedNode.color === 'string'\n ? serializedNode.color\n : DEFAULT_COLOR;\n return self;\n }\n\n exportJSON(): SerializedColoredNode {\n return {\n ...super.exportJSON(),\n color: this.__color === DEFAULT_COLOR ? undefined : this.__color,\n };\n }\n}\n```\n\nAfter — same on-the-wire JSON, no hand-written serialization:\n\n```ts\nconst colorState = createState('color', {\n parse: (v) => (typeof v === 'string' ? v : DEFAULT_COLOR),\n});\n\nexport class ColoredNode extends TextNode {\n $config() {\n return this.config('colored', {\n extends: TextNode,\n stateConfigs: [{flat: true, stateConfig: colorState}],\n });\n }\n}\n```\n\nNo `exportJSON`, `importJSON`, `updateFromJSON`, `clone`, or\n`afterCloneFrom` override is needed: `$config` installs `clone` and\n`importJSON`, and the base `exportJSON`/`updateFromJSON`/`afterCloneFrom`\non `LexicalNode`/`TextNode` already round-trip NodeState. Read the color\nvia `$getState(node, colorState)` and write it via\n`$setState(node, colorState, value)` instead of `node.__color`.\n\n:::tip\n\nFor a seamless migration, keep the JSON key name the same — for a flat\nstate, that's the first argument to `createState`. Migrating from a\nnon-flat NodeState to a flat NodeState also works: state that appears\nunder the `$` (`NODE_STATE_KEY`) is still parsed even when the state is\nconfigured as flat, and the flat value takes precedence when both are\npresent.\n\n:::\n\n## Efficiency\n\nNodeState uses a copy-on-write scheme to manage each node's state. If\nnone of the state has changed, then the NodeState instance will be\nshared across multiple versions of that node.\n\n:::info\n\nIn a given reconciliation cycle, the first time a Lexical node is marked dirty\nvia `getWritable` will create a new instance of that node. All properties\nof the previous version are set on the new instance. NodeState is stored\nas a single property, and no copying of the internal state is done\nuntil the NodeState itself is marked writable.\n\n:::\n\nWhen serializing to JSON, each key will only be stored if the value\nis not equal to the default value. This can save quite a lot of space\nand bandwidth.\n\nParsing and serialization is only done at network boundaries, when\nintegrating with JSON or Yjs. When a value changes from an external\nsource, it is only parsed once the first time it is read.\nValues that do not come from external sources are not parsed, and\nvalues that are not used are never parsed.\n\n## Capabilities\n\nCurrent:\n\n- Allows you to define and add state to any node\n- Serializes that state automatically in the node's JSON, supporting\n versioning and copy+paste\n- Works with the reconciler, TextNodes with differing state will not\n be implicitly merged\n- @lexical/yjs support, NodeState will be automatically synchronized\n like any other property\n- NodeState values that are not used will simply pass-through, making\n it a bit easier for situations where multiple configurations are used\n on the same data (e.g. older and newer versions of your editor,\n a different set of plugins based on context, etc.).\n- Pre-registration system for nodes to declare expected state\n and serialize them as top-level properties (`flat`) with `$config`\n (see [#7260](https://github.com/facebook/lexical/issues/7260)).\n- Can be integrated with\n [DOMRenderExtension](../serialization/dom-render.md) for editor\n rendering and HTML export\n- Can be integrated with\n [DOMImportExtension](../serialization/dom-import.md) for HTML import\n\nFuture:\n\n- Does not yet support direct integration with Yjs, e.g.\n you can not store a Y.Map as a NodeState value\n (see [#7293](https://github.com/facebook/lexical/issues/7293))\n\n## Node State Style Example\n\nThis example demonstrates an advanced use case of storing a style object on TextNode using NodeState.\n\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/facebook/lexical/tree/main/examples/node-state-style?file=src/main.tsx)\n\n\n\n\n---\nsidebar_label: One Lexical per app\n---\n\n# One Lexical per app\n\n`lexical` is effectively a singleton **within one app**: an app must resolve\nexactly **one** copy of `lexical`, and one copy of each `@lexical/*` package it\nuses. Two copies in the same bundle do not merely waste bytes — they break the\neditor in ways whose error messages point nowhere near the real cause.\n\nThe practical consequence, covered in [Publishing a library](#publishing-a-library)\nbelow: **a library built on Lexical declares `lexical` and the `@lexical/*`\npackages it imports as `peerDependencies`, never as `dependencies`. The\napplication brings its own Lexical.**\n\n:::note\n\nThis page is about npm `peerDependencies` in your `package.json`. Extensions\nhave their own, unrelated notion of\n[peer dependencies](../extensions/peer-dependencies.md) — optional links between\nextensions inside one editor.\n\n:::\n\n## The boundary is the app, not the page\n\nSeveral self-contained apps can share a page, each with its own bundled copy of\nLexical, and that is fine — a CMS page with two independently deployed widgets\non it, or a micro-frontend setup, does not have a bug just because two copies of\n`lexical` are loaded. Lexical anticipates this: `isLexicalEditor()` is an\n`instanceof` check specifically \"to prevent issues with multiple embedded\nLexical installations\", and an editor is tagged on its own root element rather\nthan in any page-global registry, so each app's editors resolve to that app's\nLexical and ignore the others.\n\nWhat those apps cannot do is interoperate. Two copies have no compatible API\nsurface between them, so treat each as a sealed island:\n\n- do not pass nodes, editors, `EditorState` objects, selections or commands\n across the boundary — pass serialized JSON or HTML, which is data rather than\n identity;\n- a plugin, node package or shared editor config must be bundled with the app it\n serves, not shared as a live import between apps;\n- `@lexical/react` context does not cross the boundary either, since the context\n object itself comes from one copy.\n\nThe rest of this page is about the failure case: two copies **inside one app**,\nwhere code from copy A is expected to work with an editor from copy B.\n\n## Why one copy per app\n\nLexical keeps state at module scope, and identifies things by reference rather\nthan by name. Both assumptions hold only within a single copy of the module.\n\n- **The active editor is module state.** `activeEditor`, `activeEditorState`\n and `isReadOnlyMode` live at module scope in `LexicalUpdates.ts`, and every\n `$` function reads them. `editor.update()` in copy A sets copy A's variables;\n a `$` function imported from copy B reads copy B's, which are still `null`\n ([Editor State](editor-state.md)).\n- **Node classes are compared by identity.** Node registration and the\n `instanceof LexicalNode` checks compare class references. A node that extends\n `LexicalNode` from copy A is not, as far as copy B is concerned, a\n `LexicalNode` at all — even though both classes have the same name and come\n from the same published version ([Nodes](nodes.mdx)).\n- **Commands are object identities.** `createCommand()` returns a fresh `{type}`\n object, and `registerCommand`/`dispatchCommand` match on that object, not on\n its `type` string. Two copies of `lexical` export two distinct\n `FORMAT_TEXT_COMMAND` objects, so a dispatch from one never reaches a listener\n registered with the other ([Commands](commands.md)).\n\nOn top of that, two copies are usually two *versions*, which is API drift inside\na single editor: half your plugins were compiled against a different API and\nserialization format than the editor running them, and the mismatch surfaces\nonly at runtime, on the paths that happen to differ.\n\n## Symptoms of a duplicated Lexical\n\nThe errors are unhelpfully literal — a class that plainly does implement\n`getType()` is reported as not implementing it, because the check is running\nagainst the other copy:\n\n```\nLexicalNode: Node FooNode does not implement .getType().\n\nCreate node: Type heading in node HeadingNode does not match registered node\nHeadingNode with the same type\n\ncreateEditor: nodes[0] FooNode (type foo) is not a constructor that subclasses\nLexicalNode from the lexical package used by this editor (0.50.0)\n\nUnable to find an active editor state. State helpers or node methods can only be\nused synchronously during the callback of editor.update(), editor.read(), or\neditorState.read(). Detected on the page: 0 compatible editor(s) with version\n0.50.0 and incompatible editors with versions 0.49.0\n```\n\nThat last sentence is Lexical telling you directly that it found editors built\nfrom another copy — a version different from its own, or the same version marked\n`(separately built, likely a bundler configuration issue)`. Note that this\ndiagnostic scans the whole page, so a genuinely separate app that ships its own\nLexical is counted there too; it is evidence of a bug only when those editors\nwere supposed to be part of *your* app.\n\nSilent failures look like: a command that dispatches but never fires its\nlistener, `$getSelection()` returning `null` inside an update, or a custom node\nrendering as plain text after a copy/paste. Real reports of this failure mode:\n[#4225](https://github.com/facebook/lexical/issues/4225) and\n[#7819](https://github.com/facebook/lexical/issues/7819).\n\n## Publishing a library\n\nIf you publish a package that imports from `lexical` or `@lexical/*` — a plugin,\na node package, a shared editor config, an in-house wrapper in a monorepo — put\nthose packages in `peerDependencies`, and in `devDependencies` so you can still\nbuild and test:\n\n```json\n{\n \"name\": \"my-lexical-plugin\",\n \"peerDependencies\": {\n \"lexical\": \">=0.50.0\",\n \"@lexical/react\": \">=0.50.0\",\n \"@lexical/utils\": \">=0.50.0\"\n },\n \"devDependencies\": {\n \"lexical\": \"0.50.0\",\n \"@lexical/react\": \"0.50.0\",\n \"@lexical/utils\": \"0.50.0\"\n }\n}\n```\n\nNotes on the ranges:\n\n- Lexical is pre-1.0, so `^0.50.0` means `>=0.50.0 <0.51.0` — a caret peer range\n locks your users out of the next release. Prefer an open `>=` range (or an\n explicit `>=0.50.0 <1.0.0`) so an app can upgrade Lexical without waiting for\n you.\n- Mark a peer optional with\n [`peerDependenciesMeta`](https://docs.npmjs.com/cli/configuring-npm/package-json#peerdependenciesmeta)\n when the import is behind an opt-in entry point, the way this repo's own\n packages mark `typescript` optional.\n- Do not add `lexical` to `dependencies` \"just so it installs\". That is exactly\n what pins a second copy under `node_modules/your-lib/node_modules/lexical` as\n soon as your range and the app's range disagree.\n\n## Application setup\n\nThe application owns the version, and every Lexical package it installs moves\ntogether:\n\n- Install `lexical` and each `@lexical/*` package you use **at the same\n version**. Published `@lexical/*` packages depend on the exact matching\n `lexical` version (the monorepo's `workspace:*` is rewritten to an exact\n version at publish time), so `@lexical/react@0.50.0` beside `lexical@0.49.0`\n guarantees a nested second copy.\n- Verify there is only one **per app**, from the app root:\n\n ```sh\n npm ls lexical @lexical/react # or: pnpm why lexical / yarn why lexical\n ```\n\n More than one resolved version, or a path with a nested `node_modules/lexical`\n in it, is the bug.\n- In a monorepo or a linked-package setup (`npm link`, `pnpm link`, a Yalc\n copy), the linked library resolves Lexical from *its own* `node_modules` and\n duplicates are the default rather than the exception. Deduplicate explicitly:\n hoist the dependency to the workspace root, or force resolution with\n [pnpm `overrides`](https://pnpm.io/settings#overrides), Yarn `resolutions`, or\n `npm dedupe`.\n- Bundlers can also be told to collapse duplicates — Vite\n [`resolve.dedupe`](https://vite.dev/config/shared-options.html#resolve-dedupe),\n webpack `resolve.alias` pointing each package at one path:\n\n ```js\n // vite.config.js\n export default {\n resolve: {dedupe: ['lexical', '@lexical/react', '@lexical/utils']},\n };\n ```\n\n Treat that as a safety net, not a fix: it collapses copies that are already\n version-compatible, and cannot rescue two genuinely different versions.\n- Duplication does not always come from the dependency tree: importing Lexical\n through both `import` and `require` pulls in the ESM and the CJS build of the\n *same* version, which are still two copies. The\n [React FAQ](../react/faq.md#lexicalcomposercontextuselexicalcomposercontext-cannot-find-a-lexicalcomposercontext)\n covers how this one shows up in `@lexical/react`.\n\n\n# Read Mode / Edit Mode\n\nLexical supports two modes:\n\n- Read mode\n- Edit mode\n\nThe default behavior for Lexical is edit mode, or more accurately not read only mode. Under-the-hood, the main\nimplementation detail is that the `contentEditable` is being set to `\"false\"` or `\"true\"` depending on the mode.\nSpecific plugins can listen to the mode change too – allowing them to customize parts of the UI depending on the\nmode.\n\n## Setting the mode\n\nIn order to set the mode, this can be done on creation of the editor, with the\n`editable` property of your app's extension:\n\n```js\nimport {buildEditorFromExtensions} from '@lexical/extension';\nimport {RichTextExtension} from '@lexical/rich-text';\nimport {defineExtension} from 'lexical';\n\nconst editor = buildEditorFromExtensions(\n defineExtension({\n dependencies: [RichTextExtension],\n editable: false,\n name: '@my-app/editor',\n }),\n);\n```\n\nWith React, pass the same extension to ``:\n\n```jsx\n\n ...\n\n```\n\nAfter an editor is created, the mode can be changed imperatively:\n\n```js\neditor.setEditable(true);\n```\n\n## Reading the mode\n\nIn order to find the current mode of the editor you can use:\n\n```js\nconst isEditable = editor.isEditable(); // Returns true or false\n```\n\nYou can also get notified when the editor's read only mode has changed:\n\n```js\nconst removeEditableListener = editor.registerEditableListener(\n (isEditable) => {\n // The editor's mode is passed in!\n console.log(isEditable);\n },\n);\n\n// Do not forget to unregister the listener when no longer needed!\nremoveEditableListener();\n```\n\nIn an extension, depend on\n[`WatchEditableExtension`](/docs/api/modules/lexical_extension#watcheditableextension),\nwhose output is a signal holding the current editable state, instead of\nregistering the listener yourself.\n\n\n# Selection\n\n## Types of selection\n\nLexical's selection is part of the `EditorState`. This means that for every update, or change to the editor, the\nselection always remains consistent with that of the `EditorState`'s node tree.\n\nIn Lexical, there are four types of selection possible:\n\n- `RangeSelection`\n- `NodeSelection`\n- `TableSelection` (implemented in `@lexical/table`)\n- `null`\n\nIt is possible, but not generally recommended, to implement your own selection types that implement `BaseSelection`.\n\n### `RangeSelection`\n\nThis is the most common type of selection, and is a normalization of the browser's DOM Selection and Range APIs.\n`RangeSelection` consists of three main properties:\n\n- `anchor` representing a `RangeSelection` point\n- `focus` representing a `RangeSelection` point\n- `format` numeric bitwise flag, representing any active text formats\n\nBoth the `anchor` and `focus` points refer to an object that represents a specific part of the editor. The main properties of a `RangeSelection` point are:\n\n- `key` representing the `NodeKey` of the selected Lexical node\n- `offset` representing the position from within its selected Lexical node. For the `text` type this is the character, and for the `element` type this is the child index from within the `ElementNode`\n- `type` representing either `element` or `text`.\n\n### `NodeSelection`\n\nNodeSelection represents a selection of multiple arbitrary nodes. For example, three images selected at the same time.\n\n- `getNodes()` returns an array containing the selected LexicalNodes\n\n### `TableSelection`\n\nTableSelection represents a grid-like selection like tables. It stores the key of the parent node where the selection takes place and the start and end points.\n`TableSelection` consists of three main properties:\n\n- `tableKey` representing the parent node key where the selection takes place\n- `anchor` representing a `TableSelection` point\n- `focus` representing a `TableSelection` point\n\nFor example, a table where you select row = 1 col = 1 to row 2 col = 2 could be stored as follows:\n- `tableKey = 2` table key\n- `anchor = 4` table cell (key may vary)\n- `focus = 10` table cell (key may vary)\n\nNote that `anchor` and `focus` points work the same way as `RangeSelection`.\n\n### `null`\n\nThis is for when the editor doesn't have any active selection. This is common for when the editor has been blurred or when selection\nhas moved to another editor on the page. This can also happen when trying to select non-editable components within the editor space.\n\n## Working with selection\n\nSelection can be found using the `$getSelection()` helper, exported from the `lexical` package. This function can be used within\nan update, a read, or a command listener.\n\n:::tip\n\nTo walk the document from a selection point — or to write a traversal that\nhandles empty nodes and collapsed selections correctly — see\n[Node Traversals with NodeCaret](./traversals.md).\n`$caretRangeFromSelection(selection)` converts a `RangeSelection` into the\ncaret range that traversal API works with, and\n`$setSelectionFromCaretRange(range)` converts back.\n\n:::\n\n```js\nimport {$getSelection, SELECTION_CHANGE_COMMAND} from 'lexical';\n\neditor.update(() => {\n const selection = $getSelection();\n});\n\neditorState.read(() => {\n const selection = $getSelection();\n});\n\n// SELECTION_CHANGE_COMMAND runs before reconciliation in the pending update.\neditor.registerCommand(SELECTION_CHANGE_COMMAND, () => {\n const selection = $getSelection();\n});\n```\n\nIn some cases you might want to create a new type of selection and set the editor selection to\nbe that. This can only be done in update or command listeners.\n\n```js\nimport {$setSelection, $createRangeSelection, $createNodeSelection} from 'lexical';\n\neditor.update(() => {\n // Set a range selection\n const rangeSelection = $createRangeSelection();\n $setSelection(rangeSelection);\n\n // You can also indirectly create a range selection, by calling some of the selection\n // methods on Lexical nodes.\n const someNode = $getNodeByKey(someKey);\n\n // On element nodes, this will create a RangeSelection with type \"element\",\n // referencing an offset relating to the child within the element.\n // On text nodes, this will create a RangeSelection with type \"text\",\n // referencing the text character offset.\n someNode.select();\n someNode.selectPrevious();\n someNode.selectNext();\n\n // You can use this on any node.\n someNode.selectStart();\n someNode.selectEnd();\n\n // Set a node selection\n const nodeSelection = $createNodeSelection();\n // Add a node key to the selection.\n nodeSelection.add(someKey);\n $setSelection(nodeSelection);\n\n // You can also clear selection by setting it to `null`.\n $setSelection(null);\n});\n```\n\n## Focus\n\nYou may notice that when you issue an `editor.update` or\n`editor.dispatchCommand` then the editor can \"steal focus\" if there is\na selection and the editor is editable. This is because the Lexical\nselection is reconciled to the DOM selection during reconciliation,\nand the browser's focus follows its DOM selection.\n\nIf you want to make updates or dispatch commands to the editor without\nchanging the selection, can use the `SKIP_DOM_SELECTION_TAG` update tag\n(added in v0.22.0):\n\n```js\n// Call this from an editor.update or command listener\n$addUpdateTag(SKIP_DOM_SELECTION_TAG);\n```\n\nIf you want to add this tag during processing of a `dispatchCommand`,\nyou can wrap it in an `editor.update`:\n\n```js\n// NOTE: If you are already in a command listener or editor.update,\n// do *not* nest a second editor.update! Nested updates have\n// confusing semantics (dispatchCommand will re-use the\n// current update without nesting)\neditor.update(() => {\n $addUpdateTag(SKIP_DOM_SELECTION_TAG);\n editor.dispatchCommand(/* … */);\n});\n```\n\n`SKIP_DOM_SELECTION_TAG` does not apply to the initial editor state setup\n(the `$initialEditorState` property of the root extension, or\n`initialConfig.editorState` with the legacy `LexicalComposer`). On first mount the editor still scrolls\nto and focuses the initial selection. To prevent that, call\n`$setSelection(null)` inside your initial state setup function:\n\n```js\nconst editor = buildEditorFromExtensions({\n name: '[root]',\n // ...\n $initialEditorState: () => {\n // ... build your initial nodes ...\n $setSelection(null);\n },\n});\n```\n\nIf you have to support older versions of Lexical, you can mark the editor\nas not editable during the update or dispatch.\n\n```js\n// NOTE: This code should be *outside* of your update or command listener, e.g.\n// directly in the DOM event listener\nconst prevEditable = editor.isEditable();\neditor.setEditable(false);\neditor.update(\n () => {\n // run your update code or editor.dispatchCommand in here\n }, {\n onUpdate: () => {\n editor.setEditable(prevEditable);\n },\n },\n);\n```\n\n## Reading selection across a shadow boundary\n\nIf your plugin reads the DOM selection directly — through\n`Selection.anchorNode`, `Selection.getRangeAt(0)`, or similar — and the\neditor's `contentEditable` lives inside a `ShadowRoot`, the browser retargets\nthose reads to the shadow host. See\n[Shadow DOM and iframes](./shadow-dom.md) for the shadow-aware helpers\n(`getDOMSelectionPoints`, `getDOMSelectionRange`, etc.) that return the\nun-retargeted boundary points; they fall through to the standard reads in the\nplain light DOM, so there's nothing to do until you actually mount the editor\nin a shadow tree.\n\n### Selection change timing\n\n`SELECTION_CHANGE_COMMAND` runs **before reconciliation**, in a writable update,\nfor native, programmatic, and non-range selection changes. `$getSelection()`\nreturns the pending selection; `$getPreviousSelection()` returns the selection\nfrom the last committed state. A listener can normalize the selection or edit\nnodes before that same update commits. Listeners that change the selection may\ncause another notification before commit; they must converge.\n\nThis covers programmatic changes such as `node.select()`, which notify without\nwaiting for a DOM `selectionchange` event, and non-range selections such as\n`NodeSelection` and `TableSelection`, as well as native range selections.\n\nSelection listeners use the update's normal error handling. A throwing listener\nreports through `onError` and can abort the entire pending update, including the\nedit that triggered the notification and any other edits batched into that\ncommit, just like an explicit command dispatch inside that update. Because a\nprogrammatic selection change also notifies, a listener error can abort content\nedits made in the same update. Listener edits do not have a separate rollback\nscope.\n\nThe DOM is not guaranteed to match the pending state, even for a `NodeSelection`.\nNew nodes may not have an element yet, and DOM ranges, layout, and focus may\nstill reflect the previous state. Schedule DOM-dependent work after the update\nand read the reconciled state there:\n\n```ts\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n $onUpdate(() => {\n editor.read('latest', () => {\n // Read $getSelection(), look up elements, or position floating UI here.\n });\n });\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport `$onUpdate` and `COMMAND_PRIORITY_LOW` from `lexical`. Read selection and\nnodes inside the callback rather than capturing mutable pending objects.\n`registerUpdateListener` is another option for UI that must respond to every\ncommit, including content changes that do not change the selection. Updates\nusing `SKIP_DOM_SELECTION_TAG` still deliberately leave the browser selection\nunsynchronized.\n\n#### Update tags and local edits\n\nThe notification belongs to the pending update and inherits its tags. A listener\ncan inspect them with `$hasUpdateTag`. In particular, Yjs does not sync content\nedits back to peers when the update is tagged `COLLABORATION_TAG` or\n`HISTORIC_TAG`; history also treats `HISTORIC_TAG` as replaying an existing entry.\nThis applies to content edits made by selection listeners in those updates.\n\nListeners that only apply to local editing should skip those tagged updates. If\na remote change or undo must trigger an independent local content edit, schedule\nit after the tagged commit with `$onUpdate`, then start a fresh `editor.update`:\n\n```ts\nconst $applyLocalEdit = () => {\n // Read the current selection and nodes, then apply a convergent local edit.\n};\n\neditor.registerCommand(\n SELECTION_CHANGE_COMMAND,\n () => {\n if ($hasUpdateTag(COLLABORATION_TAG) || $hasUpdateTag(HISTORIC_TAG)) {\n $onUpdate(() => editor.update($applyLocalEdit));\n } else {\n $applyLocalEdit();\n }\n return false;\n },\n COMMAND_PRIORITY_LOW,\n);\n```\n\nImport the tags and `$hasUpdateTag` from `lexical`. Re-read the state in the fresh\nupdate; it has its own collaboration and undo behavior. Calling `editor.update`\ndirectly inside the command listener queues a nested update that still belongs\nto the same tagged commit.\n\nAutomatic range and cleared-selection notifications require a connected editor\nroot. Changes committed while those notifications are skipped advance the\nselection baseline and are not replayed when the root reconnects. Non-range\nselections continue to notify in unmounted and headless editors,\nwith the same pre-reconciliation timing. Native dirty-selection notifications\nmay fire even when the selection compares equal to the previous selection.\n\n\n---\nsidebar_label: Shadow DOM and iframes\n---\n\n# Shadow DOM and iframes\n\nA Lexical editor works when its `contentEditable` lives inside an **open**\n[DOM `ShadowRoot`](https://developer.mozilla.org/docs/Web/API/ShadowRoot) (for\nexample inside a [web component](https://developer.mozilla.org/docs/Web/API/Web_components))\nor inside an `