{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "api-core-plate-controller-docs", "title": "Plate Controller", "description": "API reference for PlateController.", "files": [ { "path": "../../content/docs/api/core/plate-controller.mdx", "content": "---\ntitle: Plate Controller\ndescription: API reference for PlateController.\n---\n\n`PlateController` lets UI outside a single `` subtree read the active editor store. Use it for shared toolbars, side panels, inspectors, and multi-editor shells.\n\n## Quick Use\n\nWrap the shared UI and all editors in `PlateController`. `PlateContent` registers each mounted editor store through `PlateControllerEffect`.\n\n```tsx title=\"components/editor-shell.tsx\" showLineNumbers\nimport {\n Plate,\n PlateContent,\n PlateController,\n usePlateEditor,\n} from 'platejs/react';\n\nexport function EditorShell() {\n return (\n \n \n \n \n \n );\n}\n\nfunction MainEditor() {\n const editor = usePlateEditor({ id: 'main' });\n\n return (\n \n \n \n );\n}\n\nfunction SecondaryEditor() {\n const editor = usePlateEditor({ id: 'secondary' });\n\n return (\n \n \n \n );\n}\n```\n\n`primary` belongs on `Plate`, not on `createPlateEditor` or `usePlateEditor`.\n\n## Active Editor Lookup\n\nHooks such as `useEditorRef()` and `useEditorMounted()` normally read the nearest `Plate` store. Inside `PlateController`, the same hooks can resolve a store outside a specific editor tree.\n\n| Lookup | Behavior |\n|--------|----------|\n| `useEditorRef('main')` | Resolves the store registered for `main`. |\n| `useEditorRef()` | Resolves the active editor store, then the first mounted primary editor store. |\n| Missing store with controller | Returns the fallback store, so `useEditorRef()` returns a fallback editor. |\n| Missing store without controller | Throws `Plate hooks must be used inside a Plate or PlateController`. |\n\nController lookup order without an explicit ID:\n\n1. `activeId`\n2. each ID in `primaryEditorIds`\n3. fallback store when no store is available\n\n## Fallback Editors\n\nThe fallback editor exists so read-only UI can render while no editor is active. It is not safe for transforms.\n\n```tsx title=\"components/active-editor-label.tsx\"\nimport { useEditorMounted, useEditorRef } from 'platejs/react';\n\nexport function ActiveEditorLabel() {\n const editor = useEditorRef();\n const mounted = useEditorMounted();\n\n if (!mounted || editor.meta.isFallback) {\n return

No editor selected.

;\n }\n\n return

Active editor: {editor.id}

;\n}\n```\n\n\n Check `useEditorMounted(id?)` or `!editor.meta.isFallback` before running\n transforms from UI that lives under `PlateController`.\n\n\n## Registration\n\n`PlateControllerEffect` runs inside `PlateContent`. It registers the current `Plate` store by editor ID, appends primary editors to `primaryEditorIds`, removes them on unmount, and sets `activeId` when Slate focus enters that editor.\n\n| State | Owner | Behavior |\n|-------|-------|----------|\n| `editorStores` | `PlateControllerEffect` | Maps mounted editor IDs to their Jotai stores. Unmounted IDs are set to `null`. |\n| `primaryEditorIds` | `PlateControllerEffect` | Appends mounted editors whose `Plate` store has `primary: true`; removes them on unmount. |\n| `activeId` | `PlateControllerEffect` | Set to the focused editor ID. Cleared on unmount when the unmounted editor was active. |\n\n## API Reference\n\n### `PlateController`\n\nProvider for cross-editor lookup state.\n\n\n\n \n Shared UI and editor trees that should participate in controller lookup.\n \n \n Initial active editor ID.\n \n \" optional>\n Initial editor-store map.\n \n \n Initial primary editor ID list.\n \n\n\n\n### Controller Store State\n\n| State | Type | Default |\n|-------|------|---------|\n| `activeId` | `string \\| null` | `null` |\n| `editorStores` | `Record` | `{}` |\n| `primaryEditorIds` | `string[]` | `[]` |\n\n### `usePlateControllerStore`\n\nResolve a Plate Jotai store from the controller.\n\n\n\n \n Editor ID to resolve directly.\n \n\n\n Matching editor store, active editor store, first mounted primary editor store, or `null`.\n\n\n\n### `usePlateControllerExists`\n\nCheck whether a local controller provider exists.\n\n\n\n `true` when `usePlateControllerLocalStore()` finds a controller store.\n\n\n\n### `usePlateControllerLocalStore`\n\nRead the local controller atom store.\n\n\n\n \n Scope options passed to the generated controller store hook. A string is treated as `scope`.\n \n\n\n Local controller store hook result.\n\n\n\n### `PlateControllerEffect`\n\nRegister a `Plate` store with the nearest controller.\n\n\n\n \n Editor ID to register. Defaults to the ID from the current Plate store.\n \n\n\n\n`PlateContent` renders `PlateControllerEffect` for you. Render it directly only when you build a custom content surface that still needs controller registration.\n", "type": "registry:file", "target": "content/docs/plate/api/core/plate-controller.mdx" } ], "type": "registry:file" }