{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "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 `<Plate>` subtree. | `<PlateController>` 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    <Button\n      disabled={!hasSelection}\n      onClick={() => editor.tf.toggleMark('bold')}\n    >\n      Bold\n    </Button>\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 <pre>{JSON.stringify(editor.selection, null, 2)}</pre>;\n```\n\n## Outside Plate\n\nWrap shared UI in `PlateController` when a toolbar, side panel, or inspector\nlives outside a single `<Plate>` 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    <PlateController>\n      <ActiveEditorToolbar />\n      {children}\n    </PlateController>\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    <Button onClick={() => editor.tf.focus({ edge: 'end' })}>\n      Focus editor\n    </Button>\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    <input\n      value={search}\n      onChange={(event) => {\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/editor) |\n| Add plugin APIs and transforms. | [Plugin Methods](/docs/plugin-methods) |\n| Read plugin context inside components. | [Plugin Context](/docs/plugin-context) |\n| Browse editor query contracts. | [Editor API](/docs/api/slate/editor-api) |\n| Browse editor transform contracts. | [Editor Transforms](/docs/api/slate/editor-transforms) |\n",
      "type": "registry:file",
      "target": "content/docs/plate/(guides)/editor-methods.mdx"
    }
  ],
  "type": "registry:file"
}