\n );\n}\n```\n\n\n `editor.tf.setValue` replaces nodes at the document root. Use it for explicit\n outside-editor changes, not for every `onValueChange`.\n\n\n\n\n### Load Async Initial Content\n\nUse an async `value` function when the editor can initialize as soon as the data\nresolves.\n\n```tsx title=\"components/async-editor.tsx\" showLineNumbers\nimport { Plate, usePlateEditor } from 'platejs/react';\n\nimport { Editor, EditorContainer } from '@/components/ui/editor';\n\nexport function AsyncEditor() {\n const editor = usePlateEditor({\n autoSelect: 'end',\n value: async () => {\n const response = await fetch('/api/document');\n const data = await response.json();\n\n return data.content;\n },\n onReady: ({ isAsync, value }) => {\n if (isAsync) console.info('Loaded value:', value);\n },\n });\n\n return (\n \n \n \n \n \n );\n}\n```\n\n### Initialize Manually\n\nUse `skipInitialization` when another system owns the startup moment, such as\ncollaboration or a multi-step loader.\n\n```tsx title=\"components/manual-init-editor.tsx\" showLineNumbers {8,13-18}\nimport * as React from 'react';\nimport { Plate, usePlateEditor } from 'platejs/react';\n\nimport { Editor, EditorContainer } from '@/components/ui/editor';\n\nexport function ManualInitEditor() {\n const editor = usePlateEditor({\n skipInitialization: true,\n });\n\n React.useEffect(() => {\n void fetch('/api/document')\n .then((response) => response.json())\n .then((data) => {\n editor.tf.init({\n autoSelect: 'end',\n value: data.content,\n });\n });\n }, [editor]);\n\n return (\n \n \n \n \n \n );\n}\n```\n\n\n\nDone. Plate owns live editor state; your app controls the entry points around it.\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/controlled.mdx"
}
],
"type": "registry:file"
},
{
"name": "debugging-docs",
"title": "Debugging",
"description": "Debugging in Plate.",
"files": [
{
"path": "../../content/docs/(guides)/debugging.mdx",
"content": "---\ntitle: Debugging\ndescription: Debugging in Plate.\n---\n\n## Using the DebugPlugin\n\nThe `DebugPlugin` is automatically included when you create a Plate editor. You can access its methods through the editor's API:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [/* your plugins */],\n});\n\neditor.api.debug.log('This is a log message');\neditor.api.debug.info('This is an info message');\neditor.api.debug.warn('This is a warning');\neditor.api.debug.error('This is an error');\n```\n\n### Log Levels\n\nThe `DebugPlugin` supports four log levels:\n\n1. `log`: For general logging\n2. `info`: For informational messages\n3. `warn`: For warnings\n4. `error`: For errors\n\nYou can set the minimum log level to control which messages are displayed:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [\n DebugPlugin.configure({\n options: {\n logLevel: 'warn', // Only show warnings and errors\n },\n }),\n ],\n});\n```\n\n### Configuration Options\n\nThe `DebugPlugin` can be configured with the following options:\n\n- `isProduction`: Set to `true` to disable logging in production environments.\n- `logLevel`: Set the minimum log level (`'error'`, `'warn'`, `'info'`, or `'log'`).\n- `logger`: Provide custom logging functions for each log level.\n- `throwErrors`: Set to `true` to throw errors instead of logging them (default: `true`).\n\nExample configuration:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [\n DebugPlugin.configure({\n options: {\n isProduction: process.env.NODE_ENV === 'production',\n logLevel: 'info',\n logger: {\n error: (message, type, details) => {\n // Custom error logging\n console.error(`Custom Error: ${message}`, type, details);\n },\n // ... custom loggers for other levels\n },\n throwErrors: false,\n },\n }),\n ],\n});\n```\n\n### Error Handling\n\nBy default, the `DebugPlugin` throws errors when `error` is called. You can catch these errors and handle them as needed:\n\n```ts\ntry {\n editor.api.debug.error('An error occurred', 'CUSTOM_ERROR', { details: 'Additional information' });\n} catch (error) {\n if (error instanceof PlateError) {\n console.debug(error.type); // 'CUSTOM_ERROR'\n console.debug(error.message); // '[CUSTOM_ERROR] An error occurred'\n }\n}\n```\n\nTo log errors instead of throwing them, set `throwErrors` to `false` in the configuration.\n\n### Best Practices\n\n1. Use appropriate log levels for different types of messages.\n2. In production, set `isProduction` to `true` to disable non-essential logging.\n3. Use custom loggers to integrate with your preferred logging service.\n4. Include relevant details when logging to make debugging easier.\n5. Use error types to categorize and handle different error scenarios.\n\n## Additional Debugging Strategies\n\nBesides using the DebugPlugin, there are other effective ways to debug your Plate editor:\n\n### 1. Override Editor Methods with Logging\n\nYou can use the `extendEditor` option to override editor methods and add logging:\n\n```ts\nconst LoggingPlugin = createPlatePlugin({\n key: 'logging',\n}).overrideEditor(({ editor, tf: { apply } }) => ({\n transforms: {\n apply(operation) {\n console.debug('Operation:', operation);\n apply(operation);\n },\n },\n}));\n\nconst editor = createPlateEditor({\n plugins: [LoggingPlugin],\n});\n```\n\nThis approach allows you to log operations, selections, or any other editor behavior you want to inspect.\n\n### 2. Remove Suspected Plugins\n\nIf you're experiencing issues, try removing plugins one by one to isolate the problem:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [\n // Comment out or remove suspected plugins\n // HeadingPlugin,\n // BoldPlugin,\n // ...other plugins\n ],\n});\n```\n\nGradually add plugins back until you identify the one causing the issue.\n\n### 3. Use React DevTools\n\nReact DevTools can be invaluable for debugging Plate components:\n\n1. Install the React DevTools browser extension.\n2. Open your app and the DevTools.\n3. Navigate to the Components tab.\n4. Inspect Plate components, their props, and state.\n\n### 4. Use Browser DevTools Breakpoints\n\nSet breakpoints in your code using browser DevTools:\n\n1. Open your app in the browser and open DevTools.\n2. Navigate to the Sources tab.\n3. Find your source file and click on the line number where you want to set a breakpoint.\n4. Interact with your editor to trigger the breakpoint.\n5. Inspect variables and step through the code.\n\n### 5. Create Minimal Reproducible Examples\n\nIf you're facing a complex issue:\n\n1. Pick a [template](/docs/plate/installation).\n2. Add only the essential plugins and components to reproduce the issue.\n3. If the issue persists, [open an issue on GitHub](https://github.com/udecode/plate/issues/new?assignees=&labels=bug&projects=&template=bug.yml) or share your example on [Discord](https://discord.gg/mAZRuBzGM3).\n\n### 6. Use Redux DevTools for zustand stores\n\nZustand and thus zustand-x works with the Redux DevTools browser extension. It can be very useful to help track state changes in zustand stores.\n\nFollow the [zustand documentation](https://zustand.docs.pmnd.rs/middlewares/devtools) to get going with Redux DevTools and zustand.\n\n\n## Debug Error Types\n\nPlate uses several predefined error types to help identify specific issues during development. Here's a list of these error types and their descriptions:\n\n### DEFAULT\n\nA general error that doesn't fit into other specific categories. Used when no other error type is applicable to the situation.\n\n### OPTION_UNDEFINED\n\nThrown when an attempt is made to access an undefined plugin option. This occurs when trying to use a plugin option that hasn't been set or is undefined.\n\n### OVERRIDE_MISSING\n\nIndicates that an expected override is missing in a plugin configuration. This happens when a plugin expects certain overrides to be provided, but they are not present in the configuration.\n\n### PLUGIN_DEPENDENCY_MISSING\n\nOccurs when a required plugin dependency is not found. This error is thrown when a plugin depends on another plugin that hasn't been registered or included in the editor configuration.\n\n### PLUGIN_MISSING\n\nIndicates an attempt to use a plugin that hasn't been registered. This happens when trying to access or use a plugin that is not part of the current editor configuration.\n\n### USE_CREATE_PLUGIN\n\nThrown when a plugin wasn't created using `createSlatePlugin` or `createPlatePlugin` function. This error occurs when a plugin is added to the editor without being properly created using the designated function.\n\n### USE_ELEMENT_CONTEXT\n\nIndicates that the `useElement` hook is being used outside of the appropriate element context. This occurs when trying to access element-specific data or functionality outside of the correct component context.\n\n### PLUGIN_NODE_TYPE\n\nThrown when a plugin is incorrectly configured as both an element and a leaf. This error occurs when a plugin's configuration contradicts itself by setting both `isElement` and `isLeaf` to true.\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/debugging.mdx"
}
],
"type": "registry:file"
},
{
"name": "editing-behavior-docs",
"title": "Editing Behavior",
"description": "How Plate handles Enter, Backspace, merge, normalize, and selection behavior.",
"files": [
{
"path": "../../content/docs/(guides)/editing-behavior.mdx",
"content": "---\ntitle: Editing Behavior\ndescription: How Plate handles Enter, Backspace, merge, normalize, and selection behavior.\n---\n\nEditing behavior is the path from a key press or transform to the final document shape. Use [Plugin Rules](/docs/plate/plugin-rules) for declarative node policy, and use [Editor Methods](/docs/plate/editor-methods) when you need an imperative transform. This guide shows how break, delete, merge, normalize, and selection behavior fit together.\n\n## On This Page\n\n- [Choose the Right Surface](#choose-the-right-surface)\n- [Runtime Pipeline](#runtime-pipeline)\n- [Break Behavior](#break-behavior)\n- [Delete Behavior](#delete-behavior)\n- [Merge Behavior](#merge-behavior)\n- [Normalize Behavior](#normalize-behavior)\n- [Selection Behavior](#selection-behavior)\n- [Recipes](#recipes)\n- [API Reference](#api-reference)\n\n## Choose the Right Surface\n\nMost editing behavior belongs in `plugin.rules`. Reach for custom transforms only when the rule table cannot express the behavior.\n\n| Need | Use |\n| --- | --- |\n| Change how `Enter` works in a node. | `rules.break` |\n| Change how `Backspace` works at the start of a block. | `rules.delete` |\n| Decide whether an empty sibling disappears during a merge. | `rules.merge` |\n| Remove empty nodes during normalization. | `rules.normalize` |\n| Control mark or inline boundaries while typing and moving. | `rules.selection` |\n| Apply one plugin's rules to another node type. | `rules.match` |\n| Run product-specific behavior that rules cannot express. | `.overrideEditor()` or an explicit `editor.tf.*` command |\n\nRules keep common editor policy close to the plugin that owns the node. Transforms are still the right tool for commands, toolbar actions, and behavior that depends on app state.\n\n## Runtime Pipeline\n\nPlate resolves plugins first, then core plugins wrap Slate APIs and transforms.\n\n| Layer | Owner | Handles |\n| --- | --- | --- |\n| `OverridePlugin` | Core runtime | Node flags, break rules, delete rules, merge rules, normalize rules. |\n| `AffinityPlugin` | Core runtime | `rules.selection` for mark and inline boundaries. |\n| Feature plugins | Feature packages | Default rules for headings, callouts, lists, links, tables, marks, and other nodes. |\n| App plugins | Your app | Local overrides, custom node policy, and custom transforms. |\n\nThe normal flow is:\n\n```txt\nkey press or command\n -> optional input rule for typed patterns\n -> plugin rule lookup for the current node\n -> editor.tf transform\n -> merge guard when nodes are joined\n -> normalization\n -> selection affinity cleanup\n```\n\nInput rules are for text patterns such as markdown shortcuts and autolinks. Plugin rules are for node behavior such as \"a heading resets to paragraph on Backspace\" or \"a callout inserts soft breaks on Enter.\"\n\n## Break Behavior\n\n`rules.break` controls `editor.tf.insertBreak()`, which is what `Enter` calls.\n\nPlate checks the current block and handles these cases in order:\n\n| Case | Rule | What happens |\n| --- | --- | --- |\n| Empty collapsed block | `break.empty` | Runs `reset`, `exit`, `lift`, `deleteExit`, or falls through. |\n| Cursor after a trailing newline | `break.emptyLineEnd` | Runs `exit`, `deleteExit`, or falls through. |\n| Normal Enter | `break.default` | Runs `lineBreak`, `exit`, `deleteExit`, or falls through. |\n| Split created a new block | `break.splitReset` | Resets the new block to the default type. |\n\nUse `splitReset` for blocks that should not keep their type after a normal split.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { H1Plugin } from '@platejs/basic-nodes/react';\n\nexport const AppH1Plugin = H1Plugin.configure({\n rules: {\n break: {\n splitReset: true,\n },\n },\n});\n```\n\nUse `lineBreak` and `deleteExit` for container-like blocks that need soft lines before they leave the block.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { CalloutPlugin } from '@platejs/callout/react';\n\nexport const AppCalloutPlugin = CalloutPlugin.configure({\n rules: {\n break: {\n default: 'lineBreak',\n empty: 'reset',\n emptyLineEnd: 'deleteExit',\n },\n },\n});\n```\n\nThat callout keeps normal Enter inside the callout, resets empty callouts to paragraphs, and exits after a trailing empty line.\n\n## Delete Behavior\n\n`rules.delete` controls collapsed `Backspace` behavior. Expanded selections still delete through the normal fragment path unless the whole editor is selected.\n\nPlate checks collapsed `deleteBackward` in this order:\n\n| Case | Rule | What happens |\n| --- | --- | --- |\n| Cursor at the start of the current block | `delete.start` | Runs `reset`, `lift`, or falls through. |\n| Current block is empty | `delete.empty` | Runs `reset` or falls through. |\n| Cursor is at the start of the document | Core default | Resets the first block. |\n| Nothing handled the case | Slate transform | Runs the original delete transform. |\n\nUse `start: 'reset'` for formatted text blocks that should become paragraphs before they merge into the previous block.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { H1Plugin } from '@platejs/basic-nodes/react';\n\nexport const AppH1Plugin = H1Plugin.configure({\n rules: {\n delete: {\n start: 'reset',\n },\n },\n});\n```\n\nUse `start: 'lift'` for nested blocks that should move out one ancestor level.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { createPlatePlugin } from 'platejs/react';\n\nexport const QuoteItemPlugin = createPlatePlugin({\n key: 'quote_item',\n node: {\n isElement: true,\n },\n rules: {\n delete: {\n start: 'lift',\n },\n },\n});\n```\n\nWhen a selection spans multiple blocks, Plate deletes the selected content and then calls `editor.tf.mergeNodes()` at the end boundary. That means cross-block deletion can still enter the merge pipeline below.\n\n## Merge Behavior\n\nMerge behavior decides whether two nodes can join and whether empty nodes at the boundary disappear.\n\n`editor.tf.mergeNodes()` calls `editor.api.shouldMergeNodes(prev, next, options)` before it applies the merge. Plate's merge rules add three important guards:\n\n| Case | Behavior |\n| --- | --- |\n| Empty text node before the merge point | Remove it when it is not the first child. |\n| Empty previous sibling | Remove it only when the owning plugin has `rules.merge.removeEmpty: true`. |\n| Target node is void | Do not delete the void target by default; remove the current empty node instead when possible. |\n\nUse `removeEmpty: true` for text-like blocks such as paragraphs and headings.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { H1Plugin } from '@platejs/basic-nodes/react';\n\nexport const AppH1Plugin = H1Plugin.configure({\n rules: {\n merge: {\n removeEmpty: true,\n },\n },\n});\n```\n\nKeep `removeEmpty: false` for structural nodes that own layout, children, or wrappers. Tables, rows, cells, columns, and callouts should not disappear just because a merge crosses their boundary.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { CalloutPlugin } from '@platejs/callout/react';\n\nexport const StableCalloutPlugin = CalloutPlugin.configure({\n rules: {\n merge: {\n removeEmpty: false,\n },\n },\n});\n```\n\n\n Merge rules are not table cell merge commands. `rules.merge` protects\n document structure during node joins. Table cell merge and split commands live\n on `editor.tf.table.merge()` and `editor.tf.table.split()`.\n\n\n## Normalize Behavior\n\n`rules.normalize` runs during Slate normalization.\n\nUse `normalize.removeEmpty` for elements that should not exist without text content. Links use this shape because an empty link has no useful editing surface.\n\n```tsx title=\"plugins.tsx\" showLineNumbers\nimport { LinkPlugin } from '@platejs/link/react';\n\nexport const AppLinkPlugin = LinkPlugin.configure({\n rules: {\n normalize: {\n removeEmpty: true,\n },\n },\n});\n```\n\nKeep normalization rules boring. If a node needs a rich repair strategy, write a dedicated normalizer with `.overrideEditor()` so the behavior is explicit and testable.\n\n## Selection Behavior\n\n`rules.selection` controls how marks and inline-like boundaries behave while typing, deleting, and moving the cursor.\n\n| Affinity | Use for |\n| --- | --- |\n| `default` | Normal Slate boundary behavior. |\n| `directional` | Links and highlights where cursor direction decides whether typed text stays inside. |\n| `outward` | Comment and suggestion marks where edge typing should leave the mark. |\n| `hard` | Boundaries that should take an extra arrow-key step to cross. |\n\nNode flags also affect editing behavior. `node.isInline`, `node.isVoid`, `node.isSelectable`, and `node.isMarkableVoid` are resolved by the core override layer before selection and transform logic runs.\n\n## Recipes\n\n| Behavior | Configure |\n| --- | --- |\n| Heading resets to paragraph on Backspace. | `rules.delete.start: 'reset'` |\n| Heading splits into paragraph on Enter. | `rules.break.splitReset: true` |\n| Callout keeps Enter inside the block. | `rules.break.default: 'lineBreak'` |\n| Empty callout becomes a paragraph. | `rules.break.empty: 'reset'` or `rules.delete.start: 'reset'` |\n| Nested item outdents on Backspace. | `rules.delete.start: 'lift'` |\n| Empty text block disappears during merge. | `rules.merge.removeEmpty: true` |\n| Structural wrapper survives merge. | `rules.merge.removeEmpty: false` |\n| Empty inline element disappears. | `rules.normalize.removeEmpty: true` |\n| Link boundary follows cursor direction. | `rules.selection.affinity: 'directional'` |\n\nFor list metadata and code-block children, use `rules.match` so the feature plugin can apply its rule to the child block that actually contains the selection.\n\n## API Reference\n\n| Surface | Owner | Reference |\n| --- | --- | --- |\n| `rules.break` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesbreak) |\n| `rules.delete` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesdelete) |\n| `rules.merge` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesmerge) |\n| `rules.normalize` | Core rule engine plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesnormalize) |\n| `rules.selection` | Affinity core plugin plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesselection) |\n| `rules.match` | Core rule lookup plus feature plugin config | [Plugin Rules](/docs/plate/plugin-rules#rulesmatch) |\n| `editor.tf.mergeNodes()` | Slate transform patched by Plate | [Editor Transforms](/docs/plate/api/slate/editor-transforms#mergenodes) |\n| `editor.api.shouldMergeNodes()` | Slate editor API patched by Plate | [Editor API](/docs/plate/api/slate/editor-api#shouldmergenodes) |\n| `editor.tf.table.merge()` | Table feature package | [Table](/docs/plate/table#editing-behavior) |\n\nDone. Rules describe the policy; transforms do the work.\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/editing-behavior.mdx"
}
],
"type": "registry:file"
},
{
"name": "editor-methods-docs",
"title": "Editor Methods",
"description": "Read, mutate, and configure a Plate editor instance.",
"files": [
{
"path": "../../content/docs/(guides)/editor-methods.mdx",
"content": "---\ntitle: Editor Methods\ndescription: Read, mutate, and configure a Plate editor instance.\n---\n\nThe Plate editor exposes two main method surfaces: `editor.api` for reads and\nhelpers, and `editor.tf` for transforms that change editor state. In React, pick\nthe editor hook by how often the component should re-render.\n\n## Access the Editor\n\n| Need | Use |\n| --- | --- |\n| Read the editor inside callbacks without re-rendering. | `useEditorRef()` |\n| Re-render from one derived value. | `useEditorSelector(selector, deps)` |\n| Re-render on every editor change. | `useEditorState()` |\n| Reach the active editor from outside a `` subtree. | `` plus the same hooks. |\n\n```tsx title=\"components/bold-button.tsx\" showLineNumbers\nimport { useEditorRef, useEditorSelector } from 'platejs/react';\n\nimport { Button } from '@/components/ui/button';\n\nexport function BoldButton() {\n const editor = useEditorRef();\n const hasSelection = useEditorSelector(\n (editor) => Boolean(editor.selection),\n []\n );\n\n return (\n editor.tf.toggleMark('bold')}\n >\n Bold\n \n );\n}\n```\n\n### `useEditorRef`\n\n`useEditorRef` returns the stable editor object. Use it for event handlers,\neffects, commands, and reads that should not cause a render.\n\n```tsx title=\"components/insert-paragraph-button.tsx\"\nconst editor = useEditorRef();\n\neditor.tf.insertNodes({\n children: [{ text: 'Inserted paragraph' }],\n type: 'p',\n});\n```\n\n### `useEditorSelector`\n\n`useEditorSelector` subscribes to a derived value. Return a primitive or provide\n`equalityFn` when the selected value needs custom comparison.\n\n```tsx title=\"components/selection-state.tsx\"\nconst isSelectionExpanded = useEditorSelector(\n (editor) => editor.api.isExpanded(),\n []\n);\n```\n\n### `useEditorState`\n\n`useEditorState` subscribes to the whole editor state. Use it only when the UI\nreally needs to update on every editor change.\n\n```tsx title=\"components/selection-debug.tsx\"\nconst editor = useEditorState();\n\nreturn
{JSON.stringify(editor.selection, null, 2)}
;\n```\n\n## Outside Plate\n\nWrap shared UI in `PlateController` when a toolbar, side panel, or inspector\nlives outside a single `` tree.\n\n```tsx title=\"components/editor-shell.tsx\" showLineNumbers\nimport type React from 'react';\n\nimport { PlateController, useEditorMounted, useEditorRef } from 'platejs/react';\n\nimport { Button } from '@/components/ui/button';\n\nexport function EditorShell({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n );\n}\n\nfunction ActiveEditorToolbar() {\n const editor = useEditorRef();\n const mounted = useEditorMounted();\n\n if (!mounted || editor.meta.isFallback) return null;\n\n return (\n \n );\n}\n```\n\n`PlateController` resolves an editor by explicit `id`, focused editor, then\nprimary editors. If a controller exists but no editor store is ready, hooks\nreturn a fallback editor; check `useEditorMounted()` or\n`!editor.meta.isFallback` before running transforms.\n\n## Editor API and Transforms\n\nUse `editor.api` for queries and DOM/editor helpers. Use `editor.tf` for\noperations that change the document, selection, history, focus, or plugin state.\n`editor.transforms` is an alias for `editor.tf`.\n\n```ts title=\"editor-methods.ts\" showLineNumbers\nconst selectedText = editor.selection\n ? editor.api.string(editor.selection)\n : '';\n\nconst currentBlock = editor.api.block();\n\nif (selectedText && !editor.api.hasMark('bold')) {\n editor.tf.toggleMark('bold');\n}\n\neditor.tf.insertNodes({\n children: [{ text: 'New paragraph' }],\n type: 'p',\n});\n```\n\n| Surface | Examples | Use for |\n| --- | --- | --- |\n| `editor.api` | `string`, `block`, `findPath`, `hasMark`, `isExpanded` | Reading editor state, resolving paths, checking selection. |\n| `editor.tf` | `insertNodes`, `setNodes`, `toggleMark`, `focus`, `reset` | Mutating document or editor state. |\n| `editor.transforms` | Same as `editor.tf` | Compatibility alias. Prefer `editor.tf` in new code. |\n\n## Plugin Methods\n\nPlugin helpers let TypeScript infer APIs and transforms from the plugin you\npass in.\n\n```ts title=\"table-methods.ts\" showLineNumbers\nimport { TablePlugin } from '@platejs/table/react';\n\nconst api = editor.getApi(TablePlugin);\nconst tf = editor.getTransforms(TablePlugin);\n\nconst cell = api.create.tableCell();\n\ntf.insert.tableRow();\n```\n\n| Method | Use for |\n| --- | --- |\n| `editor.getApi(plugin)` | Typed plugin APIs merged onto `editor.api`. |\n| `editor.getTransforms(plugin)` | Typed plugin transforms merged onto `editor.tf`. |\n| `editor.getPlugin(plugin)` | The resolved plugin instance for a key or plugin object. |\n| `editor.getType(pluginKey)` | The node type registered for a plugin key. |\n| `editor.getInjectProps(plugin)` | Resolved injected node props for a plugin. |\n\n## Plugin Options\n\nUse editor option methods when imperative code needs to read or write plugin\nconfiguration. Use `usePluginOption` or `usePluginOptions` when React UI needs\nto re-render from option state.\n\n```tsx title=\"components/find-replace-control.tsx\" showLineNumbers\nimport { FindReplacePlugin } from '@platejs/find-replace';\nimport { useEditorRef, usePluginOption } from 'platejs/react';\n\nexport function FindReplaceControl() {\n const editor = useEditorRef();\n const search = usePluginOption(FindReplacePlugin, 'search');\n\n return (\n {\n editor.setOption(FindReplacePlugin, 'search', event.target.value);\n }}\n />\n );\n}\n```\n\n```ts title=\"plugin-options.ts\"\nconst options = editor.getOptions(FindReplacePlugin);\n\neditor.setOptions(FindReplacePlugin, {\n search: 'Plate',\n});\n\neditor.setOptions(FindReplacePlugin, (draft) => {\n draft.search = draft.search.trim();\n});\n```\n\n| Method | Use for |\n| --- | --- |\n| `editor.getOption(plugin, key, ...args)` | One option or selector value. |\n| `editor.getOptions(plugin)` | Current option state for a plugin. |\n| `editor.setOption(plugin, key, value)` | One option update. |\n| `editor.setOptions(plugin, partial)` | Merge multiple option fields. |\n| `editor.setOptions(plugin, updater)` | Mutate option state through a draft updater. |\n| `editor.getOptionsStore(plugin)` | Low-level access to the plugin options store. |\n\n## Next Steps\n\n| Task | Guide |\n| --- | --- |\n| Configure editor creation. | [Editor Configuration](/docs/plate/editor) |\n| Add plugin APIs and transforms. | [Plugin Methods](/docs/plate/plugin-methods) |\n| Read plugin context inside components. | [Plugin Context](/docs/plate/plugin-context) |\n| Browse editor query contracts. | [Editor API](/docs/plate/api/slate/editor-api) |\n| Browse editor transform contracts. | [Editor Transforms](/docs/plate/api/slate/editor-transforms) |\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/editor-methods.mdx"
}
],
"type": "registry:file"
},
{
"name": "editor-docs",
"title": "Editor Configuration",
"description": "Learn how to configure and customize the Plate editor.",
"files": [
{
"path": "../../content/docs/(guides)/editor.mdx",
"content": "---\ntitle: Editor Configuration\ndescription: Learn how to configure and customize the Plate editor.\n---\n\nThis guide covers the configuration options for the Plate editor, including basic setup, plugin management, and advanced configuration techniques.\n\n## Basic Editor Configuration\n\nTo create a basic Plate editor, you can use the `createPlateEditor` function, or `usePlateEditor` in a React component:\n\n```ts\nimport { createPlateEditor } from 'platejs/react';\n\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin],\n});\n```\n\n### Initial Value\n\nSet the initial content of the editor:\n\n```ts\nconst editor = createPlateEditor({\n value: [\n {\n type: 'p',\n children: [{ text: 'Hello, Plate!' }],\n },\n ],\n});\n```\n\nYou can also initialize the editor with an HTML string and the associated plugins:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [BoldPlugin, ItalicPlugin],\n value: '
This is bold and italic text!
',\n});\n```\n\nFor a comprehensive list of plugins that support HTML string deserialization, refer to the [Plugin Deserialization Rules](/docs/plate/html#plugin-deserialization-rules) section.\n\n### Async Initial Value\n\nIf you need to fetch the initial value asynchronously (e.g., from an API), you can pass an async function directly to the `value` option:\n\n```tsx\nfunction AsyncEditor() {\n const editor = usePlateEditor({\n value: async () => {\n // Simulate fetching data from an API\n const response = await fetch('/api/document');\n const data = await response.json();\n return data.content;\n },\n autoSelect: 'end',\n onReady: ({ editor, value }) => {\n console.info('Editor ready with loaded value:', value);\n },\n });\n\n if (!editor.children.length) return
Loading…
;\n\n return (\n \n \n \n \n \n );\n}\n```\n\n### Adding Plugins\n\nYou can add plugins to your editor by including them in the `plugins` array:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin, ListPlugin],\n});\n```\n\n### Max Length\n\nSet the maximum length of the editor:\n\n```ts\nconst editor = createPlateEditor({\n maxLength: 100,\n});\n```\n\n## Advanced Configuration\n\n### Editor ID\n\nSet a custom id for the editor:\n\n```ts\nconst editor = createPlateEditor({\n id: 'my-custom-editor-id',\n});\n```\n\nIf defined, you should always pass the `id` as the first argument in any editor retrieval methods.\n\n### Node ID\n\nPlate includes a built-in system for automatically assigning unique IDs to nodes, which is crucial for certain plugins and for data persistence strategies that rely on stable identifiers.\n\nThis feature is enabled by default. You can customize its behavior or disable it entirely through the `nodeId` option.\n\n#### Configuration\n\nTo configure Node ID behavior, pass an object to the `nodeId` property when creating your editor:\n\n```ts\nconst editor = usePlateEditor({\n // ... other plugins and options\n nodeId: {\n // Function to generate IDs (default: nanoid(10))\n idCreator: () => uuidv4(),\n\n // Exclude inline elements from getting IDs (default: true)\n filterInline: true, \n\n // Exclude text nodes from getting IDs (default: true)\n filterText: true,\n\n // Reuse IDs on undo/redo and copy/paste if not in document (default: false)\n // Set to true if IDs should be stable across such operations.\n reuseId: false,\n\n // Control initial-value ID assignment (default: 'if-needed')\n // Use 'always' to fill every missing ID in the initial value.\n initialValueIds: 'always',\n \n // Prevent overriding IDs when inserting nodes with an existing id (default: false)\n disableInsertOverrides: false,\n\n // Only allow specific node types to receive IDs (default: all)\n allow: ['p', 'h1'], \n\n // Exclude specific node types from receiving IDs (default: [])\n exclude: ['code_block'],\n\n // Custom filter function to determine if a node should get an ID\n filter: ([node, path]) => {\n // Example: Only ID on top-level blocks\n return path.length === 1;\n },\n },\n});\n```\n\n\n The `NodeIdPlugin` (which handles this) is part of the core plugins and is automatically included. You only need to specify the `nodeId` option if you want to customize its default behavior.\n\n\n#### Disabling Node IDs\n\nIf you don't need automatic node IDs, you can disable the feature:\n\n```ts\nconst editor = usePlateEditor({\n // ... other plugins and options\n nodeId: false, // This will disable the NodeIdPlugin\n});\n```\n\nBy disabling this, certain plugins that rely on node IDs will not function properly. The following plugins require block IDs to work:\n\n- **[Block Selection](/docs/plate/block-selection)** - Needs IDs to track which blocks are selected\n- **[Block Menu](/docs/plate/block-menu)** - Requires IDs to show context menus for specific blocks \n- **[Drag & Drop](/docs/plate/dnd)** - Uses IDs to identify blocks during drag operations\n- **[Table](/docs/plate/table)** - Relies on IDs for cell selection\n- **[Table of Contents](/docs/plate/toc)** - Needs heading IDs for navigation and scrolling\n- **[Toggle](/docs/plate/toggle)** - Uses IDs to track which toggles are open/closed\n\n### Navigation Feedback\n\nPlate also includes a built-in navigation feedback plugin for \"you landed here\"\nUX after TOC jumps, footnote navigation, search jumps, and custom outline\nmovement.\n\nThis feature is enabled by default. You only need to touch the\n`navigationFeedback` option when you want to change the flash duration or turn\nthe plugin off.\n\n#### Configuration\n\n```ts\nconst editor = createPlateEditor({\n navigationFeedback: {\n duration: 1200,\n },\n});\n```\n\n\n The `NavigationFeedbackPlugin` is part of the core plugins and is\n automatically included. Use `navigationFeedback` for normal configuration and\n keep `rootPlugin.configurePlugin(...)` for advanced escape-hatch work.\n\n\n#### Disabling Navigation Feedback\n\n```ts\nconst editor = createPlateEditor({\n navigationFeedback: false,\n});\n```\n\n### Normalization\n\nControl whether the editor should normalize its content on initialization:\n\n```ts\nconst editor = createPlateEditor({\n shouldNormalizeEditor: true,\n});\n```\n\nNote that normalization may take a few dozen milliseconds for large documents, such as the playground value.\n\n### Auto-selection\n\nConfigure the editor to automatically select a range:\n\n```ts\nconst editor = createPlateEditor({\n autoSelect: 'end', // or 'start', or true\n});\n```\n\nThis is not the same as auto-focus: you can select text without focusing the editor.\n\n### Component Overrides\n\nOverride default components for plugins:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin],\n components: {\n [ParagraphPlugin.key]: CustomParagraphComponent,\n [HeadingPlugin.key]: CustomHeadingComponent,\n },\n});\n```\n\n### Plugin Overrides\n\nOverride specific plugin configurations:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin],\n override: {\n plugins: {\n [ParagraphPlugin.key]: {\n options: {\n customOption: true,\n },\n },\n },\n },\n});\n```\n\n### Disable Plugins\n\nDisable specific plugins:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin, ListPlugin],\n override: {\n enabled: {\n [HistoryPlugin.key]: false,\n },\n },\n});\n```\n\n### Overriding Plugins\n\nYou can override core plugins or previously defined plugins by adding a plugin with the same key. The last plugin with a given key wins:\n\n```ts\nconst CustomParagraphPlugin = createPlatePlugin({\n key: 'p',\n // Custom implementation\n});\n\nconst editor = createPlateEditor({\n plugins: [CustomParagraphPlugin],\n});\n```\n\n### Root Plugin\n\nFrom the root plugin, you can configure any plugin:\n\n```ts\nconst editor = createPlateEditor({\n plugins: [HeadingPlugin],\n rootPlugin: (plugin) =>\n plugin.configurePlugin(LengthPlugin, {\n options: {\n maxLength: 100,\n },\n }),\n});\n```\n\n## Typed Editor\n\n`createPlateEditor` will automatically infer the types for your editor from the value and the plugins you pass in. For explicit type creation, use the generics:\n\n### Plugins Type\n\n```ts\nconst editor = createPlateEditor({\n plugins: [TablePlugin, LinkPlugin],\n});\n\n// Usage\neditor.tf.insert.tableRow()\n```\n\n### Value Type\n\nFor more complex editors, you can define your types in a separate file (e.g., `plate-types.ts`):\n\n```ts\nimport type { TElement, TText } from 'platejs';\nimport type { TPlateEditor } from 'platejs/react';\n\n// Define custom element types\ninterface ParagraphElement extends TElement {\n align?: 'left' | 'center' | 'right' | 'justify';\n children: RichText[];\n type: typeof ParagraphPlugin.key;\n}\n\ninterface ImageElement extends TElement {\n children: [{ text: '' }]\n type: typeof ImagePlugin.key;\n url: string;\n}\n\n// Define custom text types\ninterface FormattedText extends TText {\n bold?: boolean;\n italic?: boolean;\n}\n\nexport type MyRootBlock = ParagraphElement | ImageElement;\n\n// Define the editor's value type\nexport type MyValue = MyRootBlock[];\n\n// Define the custom editor type\nexport type MyEditor = TPlateEditor;\n\nexport const useMyEditorRef = () => useEditorRef();\n\n// Usage\nconst value: MyValue = [{\n type: 'p',\n children: [{ text: 'Hello, Plate!' }],\n}]\n\nconst editorInferred = createPlateEditor({\n plugins: [TablePlugin, LinkPlugin],\n value,\n});\n\n// or \nconst editorExplicit = createPlateEditor({\n plugins: [TablePlugin, LinkPlugin],\n value,\n});\n```\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/editor.mdx"
}
],
"type": "registry:file"
},
{
"name": "feature-kits-docs",
"title": "Feature Kits",
"description": "Use registry kits to add groups of Plate plugins and UI wiring.",
"files": [
{
"path": "../../content/docs/(guides)/feature-kits.mdx",
"content": "---\ntitle: Feature Kits\ndescription: Use registry kits to add groups of Plate plugins and UI wiring.\n---\n\nFeature kits are app-owned registry files that group related Plate plugins, components, shortcuts, input rules, and helper UI.\nUse them to start from working Plate UI wiring, then edit the installed kit when your app needs different behavior.\n\n## Kit Types\n\n| Kit type | Example | Use for |\n| --- | --- | --- |\n| Client/UI kit | `basic-nodes-kit`, `table-kit`, `media-kit` | Editable React editors with Plate UI components. |\n| Base kit | `basic-blocks-base-kit`, `table-base-kit` | Static rendering and server-safe editor setup. |\n| Full editor kit | `editor-kit` | A complete client editor feature stack. |\n| Full base kit | `editor-base-kit` | A broad static/base plugin stack. |\n\nFeature kits live under `components/editor/plugins` after installation. Full\neditor kits like `editor-kit` and `editor-base-kit` live under\n`components/editor`. They are normal TypeScript files in your app, not package\nexports locked inside `node_modules`.\n\n## Use a Kit\n\nInstall the kit through the Plate registry, then import it from your app.\n\n```tsx title=\"components/editor.tsx\" showLineNumbers\nimport { Plate, usePlateEditor } from 'platejs/react';\n\nimport { BasicNodesKit } from '@/components/editor/plugins/basic-nodes-kit';\nimport { TableKit } from '@/components/editor/plugins/table-kit';\nimport { Editor, EditorContainer } from '@/components/ui/editor';\n\nexport function MyEditor() {\n const editor = usePlateEditor({\n plugins: [...BasicNodesKit, ...TableKit],\n });\n\n return (\n \n \n \n \n \n );\n}\n```\n\n`BasicNodesKit` composes `BasicBlocksKit` and `BasicMarksKit`. For example,\n`BasicBlocksKit` wires paragraph, headings, blockquote, and horizontal rule\nplugins to their Plate UI components; `BasicMarksKit` wires marks, input rules,\nshortcuts, and mark leaf components.\n\n## Choose the Right Kit\n\n| Need | Start with |\n| --- | --- |\n| Paragraphs, headings, blockquotes, marks. | `basic-nodes-kit` |\n| Tables with table UI components. | `table-kit` |\n| Images, video, audio, files, embeds, captions. | `media-kit` |\n| Comments and discussions. | `comment-kit` plus `discussion-kit` |\n| AI menu, AI nodes, cursor overlay, and Markdown support. | `ai-kit` |\n| Full editable editor stack. | `editor-kit` |\n| Static or server-rendered output. | `editor-base-kit` or focused `*-base-kit` files |\n\nPlugin pages show the recommended kit in their installation section. Use the kit\nsource when you need the exact plugin list, imported UI components, shortcuts,\nor registry dependencies.\n\n## Base Kits\n\nBase kits use base plugins and static components. They are the right starting\npoint for [Static Rendering](/docs/plate/static), [Node.js](/docs/plate/installation/node),\nand other non-editable pipelines.\n\n```ts title=\"static-editor.ts\"\nimport { BaseEditorKit } from '@/components/editor/editor-base-kit';\nimport { createStaticEditor } from 'platejs/static';\n\nconst editor = createStaticEditor({\n plugins: BaseEditorKit,\n});\n```\n\nUse client kits in editable React editors. Use base kits when React editor hooks,\neditable components, floating UI, or browser-only behavior should stay out of\nthe runtime.\n\n## Customize a Kit\n\nBecause kits are copied into your app, the cleanest customization is usually to\nedit the installed kit file.\n\n```tsx title=\"components/editor/plugins/my-basic-kit.tsx\"\nimport { H1Plugin } from '@platejs/basic-nodes/react';\nimport { ParagraphPlugin } from 'platejs/react';\n\nimport { H1Element } from '@/components/ui/heading-node';\nimport { ParagraphElement } from '@/components/ui/paragraph-node';\n\nexport const MyBasicKit = [\n ParagraphPlugin.withComponent(ParagraphElement),\n H1Plugin.configure({\n node: {\n component: H1Element,\n },\n shortcuts: {\n toggle: { keys: 'mod+alt+1' },\n },\n }),\n];\n```\n\nUse manual plugin setup when you only need a small part of a kit, when the app\ndoes not use Plate UI components, or when a feature needs a different dependency\nboundary.\n\n## Registry Names\n\nKits are registry items. These names map to files in\n`components/editor/plugins` or `components/editor`.\n\n| Registry item | Installs |\n| --- | --- |\n| `basic-nodes-kit` | `BasicNodesKit`, `BasicBlocksKit`, and `BasicMarksKit` dependencies. |\n| `table-kit` | `TableKit` and table UI components. |\n| `media-kit` | `MediaKit` without a media upload API route. |\n| `media-uploadthing-kit` | `media-kit` plus the UploadThing API route. |\n| `editor-kit` | The full editable editor kit. |\n| `editor-base-kit` | The full static/base kit. |\n\n## Next Steps\n\n| Task | Guide |\n| --- | --- |\n| Install registry items. | [Plate UI](/docs/plate/installation/plate-ui) |\n| Configure editor creation. | [Editor Configuration](/docs/plate/editor) |\n| Compose plugin APIs and options. | [Plugin Methods](/docs/plate/plugin-methods) |\n| Render without an editable React editor. | [Static Rendering](/docs/plate/static) |\n",
"type": "registry:file",
"target": "content/docs/plate/(guides)/feature-kits.mdx"
}
],
"type": "registry:file"
},
{
"name": "form-docs",
"title": "Form",
"description": "How to integrate Plate editor with react-hook-form.",
"files": [
{
"path": "../../content/docs/(guides)/form.mdx",
"content": "---\ntitle: Form\ndescription: How to integrate Plate editor with react-hook-form.\n---\n\nWhile Plate is typically used as an **uncontrolled** input, there are valid scenarios where you want to integrate the editor within a form library like [**react-hook-form**](https://www.react-hook-form.com) or the [**Form**](https://ui.shadcn.com/docs/components/form) component from **shadcn/ui**. This guide walks through best practices and common pitfalls.\n\n## When to Integrate Plate with a Form\n\n- **Form Submission**: You want the editor's content to be included along with other fields (e.g., ``, `\n\n \n \n );\n}\n```\n\n**Notes**:\n1. **`defaultValues.content`**: your initial editor content.\n2. **`register('content')`**: signals to RHF that the field is tracked. \n3. **`onChange({ value })`**: calls `setValue('content', value)` each time.\n\nIf you expect large documents or fast typing, consider debouncing or switching to an `onBlur` approach to reduce form updates.\n\n### shadcn/ui Form Example\n\n[shadcn/ui](https://ui.shadcn.com/docs/components/form) provides a `\n \n \n \n )}\n />\n\n \n \n \n );\n}\n```\n\nThis approach makes your editor content behave like any other field in the shadcn/ui form.\n\n## Approach 2: Sync on Blur (or Another Trigger)\n\nInstead of syncing on every keystroke, you might only need the final value when the user:\n- Leaves the editor (`onBlur`),\n- Clicks a “Save” button, or\n- Reaches certain form submission logic.\n\n```tsx\n\n {\n // Only sync on blur\n setValue('content', editor.children);\n }}\n />\n\n```\n\nThis reduces overhead but your form state won't reflect partial updates while the user is typing.\n\n## Approach 3: Controlled Replacement (Advanced)\n\nIf you want the form to be the single source of truth (completely [controlled](/docs/plate/controlled)):\n```ts\neditor.tf.setValue(formStateValue);\n```\nBut this has known drawbacks:\n- Potentially breaks cursor position and undo/redo.\n- Can cause frequent full re-renders for large docs.\n\n**Recommendation**: Stick to a partially uncontrolled model if you can.\n\n## Example: Save & Reset\n\nHere's a more complete form demonstrating both saving and resetting the editor/form:\n\n```tsx\nimport { useForm } from 'react-hook-form';\nimport { Plate, PlateContent, usePlateEditor } from 'platejs/react';\n\nfunction MyForm() {\n const form = useForm({\n defaultValues: {\n content: [\n { type: 'p', children: [{ text: 'Initial content...' }] },\n ],\n },\n });\n\n const editor = usePlateEditor();\n\n const onSubmit = (data) => {\n alert(JSON.stringify(data, null, 2));\n };\n\n return (\n \n\n \n\n {\n // Reset the editor\n editor.tf.reset();\n // Reset the form\n form.reset();\n }}\n >\n Reset\n \n \n );\n}\n```\n\n- **`onChange`** -> updates form state.\n- **Reset** -> calls both `editor.tf.reset()` and `form.reset()` for consistency.\n\n## Migrating from a shadcn Textarea to Plate\n\nIf you have a standard [TextareaForm from shadcn/ui docs](https://ui.shadcn.com/docs/components/textarea#form) and want to replace `