{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "api-core-plate-components-docs",
"title": "Plate Components",
"description": "API reference for Plate React components.",
"files": [
{
"path": "../../content/docs/api/core/plate-components.mdx",
"content": "---\ntitle: Plate Components\ndescription: API reference for Plate React components.\n---\n\nPlate components connect a `PlateEditor` to React rendering. Use `Plate` and `PlateContent` for editable editors, `PlateView` for read-only static views, and the node primitives when writing custom plugin components.\n\n## Editable Editor\n\n`Plate` owns the editor store. `PlateContent` renders the editable surface under that store.\n\n```tsx title=\"components/editor.tsx\"\nimport { Plate, PlateContent, usePlateEditor } from 'platejs/react';\n\nexport function Editor() {\n const editor = usePlateEditor({\n value: [\n {\n children: [{ text: 'Start writing.' }],\n type: 'p',\n },\n ],\n });\n\n return (\n \n \n \n );\n}\n```\n\n\n `PlateContent` must render below `Plate`. Hooks such as `useEditorRef`,\n `useEditorReadOnly`, and `usePlateStore` throw when there is no `Plate` or\n `PlateController` above them.\n\n\n## Read-Only View\n\nUse `PlateView` with a static editor when you need rendered content and Plate copy behavior without an editable surface.\n\n```tsx title=\"components/read-only-editor.tsx\"\nimport { PlateView, usePlateViewEditor } from 'platejs/react';\n\nconst value = [\n {\n children: [{ text: 'Published content.' }],\n type: 'p',\n },\n];\n\nexport function ReadOnlyEditor() {\n const editor = usePlateViewEditor({ value });\n\n if (!editor) return null;\n\n return ;\n}\n```\n\n`PlateView` wraps `PlateStatic`. Its default `onCopy` writes Plate fragment data to the clipboard, unless you pass your own `onCopy` prop.\n\n## Component Map\n\n| Component | Use For |\n|-----------|---------|\n| `Plate` | Store provider for one editor instance. |\n| `PlateContent` | Editable Slate surface with plugin handlers, decorators, renderers, hotkeys, and editor effects. |\n| `PlateView` | Static read-only rendering with Plate fragment copy support. |\n| `PlateContainer` | Editor container `div` plus `beforeContainer` and `afterContainer` plugin slots. |\n| `PlateSlate` | Slate provider wrapper used by `PlateContent`; also applies `aboveSlate` plugin wrappers. |\n| `PlateElement` | Default element renderer for block and inline elements. |\n| `PlateLeaf` | Default decorated text-leaf renderer. |\n| `PlateText` | Default text-node renderer for non-decoration leaf rendering. |\n| `ContentVisibilityChunk` | Default chunk renderer when chunking uses `content-visibility: auto`. |\n| `PlateTest` | Test helper that creates or wraps an editor and renders `PlateContent` with test attributes. |\n\n## Render Pipeline\n\n`PlateContent` builds the editable props with `useEditableProps`. That pipeline combines store-level renderers, `PlateContent` render props, plugin decorators, plugin DOM handlers, and chunking.\n\n| Stage | Source |\n|-------|--------|\n| Slate provider | `PlateSlate` uses `editor.children`, `editor.meta.key`, and store callbacks. |\n| Editable props | `useEditableProps` pipes decorators, DOM handlers, `renderChunk`, `renderElement`, `renderLeaf`, and `renderText`. |\n| Plugin slots | `beforeEditable`, `aboveEditable`, and `afterEditable` wrap or sit around the editable surface. |\n| Effects | `EditorMethodsEffect`, `EditorHotkeysEffect`, `EditorRefEffect`, and `PlateControllerEffect` run inside `PlateContent`. |\n| Read-only state | `disabled` forces read-only; `readOnly` syncs back into the Plate store. |\n\n## Node Primitives\n\nUse `PlateElement`, `PlateLeaf`, and `PlateText` inside plugin components. They merge Slate attributes with your `className`, `style`, and `ref`.\n\n```tsx title=\"components/paragraph-element.tsx\"\nimport { PlateElement, type PlateElementProps } from 'platejs/react';\n\nexport function ParagraphElement(props: PlateElementProps) {\n return ;\n}\n```\n\n| Primitive | Behavior |\n|-----------|----------|\n| `PlateElement` | Adds `data-slate-node=\"element\"`, preserves inline metadata, sets `data-block-id` for mounted block elements with an `id`, and adds directional-affinity spacers when needed. |\n| `PlateLeaf` | Renders a text leaf and adds hard-affinity spacers when needed. |\n| `PlateText` | Renders a text node without leaf-decoration matching. |\n| `useNodeAttributes` | Merges Slate attributes, refs, class names, and styles for node primitives. |\n\n## API Reference\n\n### `Plate`\n\nRoot provider for one editor instance.\n\n\n\n \n Editor instance. When `null`, `Plate` renders nothing.\n \n \n React children that can read the Plate store.\n \n TRange[]\" optional>\n Store-level decorate function used by `PlateContent`.\n \n \n Store-level read-only state. Defaults to `editor.dom.readOnly`.\n \n \n Registers the editor as a primary editor for `PlateController`.\n \n \n Fallback element renderer stored on the Plate store.\n \n \n Fallback leaf renderer stored on the Plate store.\n \n void\" optional>\n Runs after Slate change handling when plugin `onChange` handlers do not handle the event.\n \n void\" optional>\n Runs when Slate reports a value change.\n \n void\" optional>\n Runs when Slate reports a selection change.\n \n void\" optional>\n Stored on `SlateExtensionPlugin` by `PlateContent` and called for node operations.\n \n void\" optional>\n Stored on `SlateExtensionPlugin` by `PlateContent` and called for text operations.\n \n \n Suppresses the multiple-instance warning from `usePlateInstancesWarn`.\n \n\n\n\n### `PlateContent`\n\nEditable surface for a `Plate` editor.\n\n\n\n \n Editor scope used by `useEditorRef(id)` and `usePlateStore(id)`.\n \n \n Focuses the editor at the end when `readOnly` changes from `true` to `false`.\n \n \n Forces read-only state and sets `aria-disabled`.\n \n \n Overrides the store read-only value and syncs it back to the store.\n \n TRange[]\" optional>\n Editable-level decorate function. Store-level `decorate` wins when present.\n \n React.ReactNode\" optional>\n Wraps or replaces the generated `Editable` element.\n \n \n Custom chunk renderer. Defaults to `ContentVisibilityChunk` when chunking enables `contentVisibilityAuto`.\n \n \n Fallback element renderer after plugin renderers.\n \n \n Fallback leaf renderer after plugin leaf renderers.\n \n \n Fallback text renderer after non-decoration text renderers.\n \n \n Placeholder renderer passed to Slate `Editable`.\n \n \n Placeholder text passed to Slate `Editable`.\n \n void\" optional>\n Slate selection scrolling hook.\n \n void\" optional>\n DOM before-input handler passed through the plugin handler pipeline.\n \n void\" optional>\n Keyboard handler passed through the plugin handler pipeline.\n \n \n Element type passed to Slate `Editable`.\n \n \n Passed to Slate `Editable`.\n \n \n ARIA role passed to Slate `Editable`.\n \n \n Style object passed to Slate `Editable`.\n \n\n\n\n`PlateContent` also accepts the DOM handler props listed in `DOMHandlers`, including clipboard, composition, focus, keyboard, pointer, mouse, drag, touch, media, and form handlers.\n\n### `PlateView`\n\nRead-only static renderer with Plate copy support.\n\n\n\n \n Static editor instance.\n \n \n Controlled value alias. When present, `PlateStatic` assigns it to `editor.children`.\n \n \" optional>\n Overrides the default Plate fragment copy handler.\n \n \n Merged with the `slate-editor` class by `PlateStatic`.\n \n \n Style object passed to the static root `div`.\n \n\n\n\n### `PlateContainer`\n\nContainer `div` with plugin container slots.\n\n\n\n \n Content rendered inside the container.\n \n \" optional>\n HTML props passed to the container `div` and container slot components.\n \n\n\n\n### Render Primitives\n\n| API | Default Element | Notes |\n|-----|-----------------|-------|\n| `PlateElement` | `div` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `element`, `path`, `editor`, `plugin`, and `insetProp`. |\n| `PlateLeaf` | `span` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `leaf`, `text`, `editor`, `plugin`, and `inset`. |\n| `PlateText` | `span` | Accepts `as`, `attributes`, `className`, `style`, `ref`, `text`, `editor`, and `plugin`. |\n| `ContentVisibilityChunk` | `div` | Wraps children only when `lowest` is true. |\n| `withHOC` | `React.forwardRef` | Wraps one ref-capable component with another ref-capable component. |\n",
"type": "registry:file",
"target": "content/docs/plate/api/core/plate-components.mdx"
}
],
"type": "registry:file"
}