{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "api-core-docs",
"title": "Plate Core",
"description": "API reference for @platejs/core.",
"files": [
{
"path": "../../content/docs/api/core.mdx",
"content": "---\ntitle: Plate Core\ndescription: API reference for @platejs/core.\n---\n\n## API\n\n### `createPlateEditor`\n\nGenerates a new instance of a `PlateEditor`, initialized with a set of plugins and their configurations.\n\n\n\n \n Unique identifier for the editor.\n \n \n Initial editor without `withPlate`.\n \n \n An array of editor plugins.\n \n V | Promise)\" optional>\n Initial value of the editor. Can be:\n - A static value array\n - An HTML string to be deserialized\n - A function that returns a value (can be async)\n \n \n Select the editor after initialization.\n - **Default:** `false`\n - `true` | 'end': Select the end of the editor\n - `false`: Do not select anything\n - `'start'`: Select the start of the editor\n \n void\" optional>\n Callback called when the editor initialization completes. The `isAsync` flag indicates whether the value was loaded asynchronously.\n \n \n Specifies the maximum number of characters allowed in the editor.\n \n \n Configuration for the built-in navigation feedback plugin.\n \n \n Default flash duration in milliseconds.\n - **Default:** `1600`\n \n \n \n \n Configuration for automatic node ID generation and management.\n \n \n Disable using existing IDs when inserting nodes.\n - When `false`: Keeps existing IDs if they don't exist in document\n - When `true`: Always generates new IDs\n - **Default:** `false`\n \n \n Filter inline Element nodes from receiving IDs.\n - **Default:** `true`\n \n \n Filter Text nodes from receiving IDs.\n - **Default:** `true`\n \n any\" optional>\n Function to generate unique IDs.\n - **Default:** `() => nanoid(10)`\n \n \n Property key used to store node IDs.\n - **Default:** `'id'`\n \n \n Controls how missing IDs are assigned in the initial value.\n - When `'if-needed'`: Only checks the first and last top-level nodes\n - When `'always'`: Walks the whole initial value and fills missing IDs\n - When `false`: Skips initial-value ID assignment\n - **Default:** `'if-needed'`\n \n \n Deprecated alias for `initialValueIds`.\n - When `false`: Same as `'if-needed'`\n - When `true`: Same as `'always'`\n - When `null`: Same as `false`\n \n \n Reuse IDs on undo/redo and copy/paste.\n - When `true`: Keeps IDs if they don't exist in document\n - When `false`: Always generates new IDs (safer across documents)\n - **Default:** `false`\n \n \n Node types that should receive IDs.\n \n \n Node types that should not receive IDs.\n \n boolean\" optional>\n Custom filter function for nodes that should receive IDs.\n - **Default:** `() => true`\n \n \n \n \n Configure Slate's chunking optimization, which reduces latency while typing. Set to `false` to disable. [Learn more about chunking.](https://docs.slatejs.org/walkthroughs/09-performance)\n \n \n The number of blocks per chunk.\n - **Default:** 1000\n \n \n Whether to render each chunk as a DOM element with `content-visibility: auto`, which optimizes DOM painting. When set to `false`, no DOM element will be rendered for each chunk.\n - **Default:** `true`\n \n boolean\" optional>\n Determine which ancestors should have chunking applied to their children. Only blocks containing other blocks can have chunking applied.\n - **Default:** `NodeApi.isEditor`\n \n \n \n \n Initial selection for the editor.\n \n \n When `true`, it will normalize the initial `value` passed to the `editor`.\n - **Default:** `false`\n \n AnyPlatePlugin\" optional>\n Function to configure the root plugin.\n \n \n API methods for the editor.\n \n \n Decoration function for the editor.\n \n \n Function to extend the editor.\n \n \n Event handlers for the editor.\n \n \n Injection configuration for the editor.\n \n \n Function to transform the initial value before the editor is ready.\n \n \n Deprecated alias for `transformInitialValue`. Legacy hooks may either\n mutate `value` in place or return the next value.\n \n \n Additional options for the editor.\n \n \n Override configuration for the editor.\n \n \n Priority of the editor plugin.\n \n \n Editor read-only initial state. For dynamic value, use\n `Plate.readOnly` prop.\n \n \n Render functions for the editor.\n \n \n Keyboard shortcuts for the editor.\n \n \n Transform functions for the editor.\n \n \n Hook to use with the editor.\n \n\n\n\n An editor instance with plugins and config applied.\n\n\n\nFor more details on editor configuration, refer to the [Editor Configuration](/docs/editor) guide.\n\n### `createPlatePlugin`\n\nCreates a new Plate plugin with the given configuration, supporting extension, nested plugin manipulation, and runtime configuration.\n\n\n\n PlatePluginConfig)\">\n The configuration object for the plugin, or a function that returns the configuration. If a function is provided, it will be executed when the plugin is resolved with the editor.\n\n For details on the `PlatePluginConfig` type, refer to the [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties).\n \n\n\n\n A new plugin instance.\n\n\n\n### `createTPlatePlugin`\n\nExplicitly typed version of `createPlatePlugin`.\n\n\n\n | ((editor: PlateEditor) => TPlatePluginConfig)\">\n The configuration object for the plugin, or a function that returns the configuration. This version requires an explicit type parameter `C` extending `AnyPluginConfig`.\n\n For details on the `TPlatePluginConfig` type, refer to the [PlatePlugin API](/docs/api/core/plate-plugin#plugin-properties).\n \n\n\n\">\n A new plugin instance.\n\n\n\n### `toPlatePlugin`\n\nExtends a SlatePlugin to create a React PlatePlugin.\n\n\n\n \n The base SlatePlugin to be extended.\n \n ) => PlatePluginConfig)\" optional>\n A function or object that provides the extension configuration. If a function, it receives the plugin context and should return a partial PlatePlugin. If an object, it should be a partial PlatePlugin configuration.\n \n\n\n\n A new plugin instance that combines the base SlatePlugin functionality with React-specific features defined in the extension configuration.\n\n\n\n### `toTPlatePlugin`\n\nExplicitly typed version of `toPlatePlugin`.\n\n\n\n \">\n The base SlatePlugin to be extended.\n \n | ((ctx: PlatePluginContext) => ExtendPluginConfig)\" optional>\n A function or object that provides the extension configuration. This version requires explicit type parameters for both the base plugin configuration (`TContext`) and the extension configuration (`C`).\n \n\n\n\">\n A new plugin instance with precise type control.\n\n\n\n### `usePlateEditor`\n\nCreates a memoized Plate editor for React components.\n\n\n\n void }\" optional>\n Configuration options for creating the Plate editor. All options from `createPlateEditor` are supported, plus:\n \n \n Whether the editor should be created. When `false`, returns `null`.\n - **Default:** `true`\n \n void\" optional>\n Callback called when the editor initialization completes. The `isAsync` flag indicates whether the value was loaded asynchronously.\n \n \n \n \n Additional dependencies for the useMemo hook.\n - **Default:** `[]`\n \n\n\n\n A memoized Plate editor instance. Returns `null` if `enabled` is `false`.\n\n\n\n### `useEditorContainerRef`\n\n\n\">\n The editor container DOM reference.\n\n\n\n### `useEditorScrollRef`\n\n\n\">\n The editor scroll container DOM reference.\n\n\n\n### `useScrollRef`\n\n\n\">\nThe editor scroll container reference. Returns the scroll ref if it exists, otherwise returns the container ref.\n\n\n\n### `useEditorPlugin`\n\nGet editor and plugin context.\n\n\n\n \">\n The plugin or plugin configuration with a required key.\n \n\n\n\n \n The current editor instance.\n \n \n The plugin instance.\n \n \n Function to get a specific option value.\n \n \n Function to get all options for the plugin.\n \n \n Function to set a specific option value.\n \n \n Function to set multiple options.\n \n \n The Plate store for the editor.\n \n\n\n\n### `useEditorRef`\n\nGet the Plate editor reference without re-rendering. The returned editor object is enhanced with a `store` property that provides access to the Plate store.\n\n\n\n \n Editor ID used for accessing nested editors. When not provided, returns the closest editor instance in the React tree. Only use this parameter when working with nested editors to target a specific scope.\n \n\n\n\n The editor reference with attached store.\n\n\n\n### `useEditorSelector`\n\nSubscribe to a specific property of the editor.\n\n\n\n , prev?: T) => T\">\n The selector function.\n \n \n The dependency list for the selector function.\n \n \" optional>\n Options for the selector function.\n \n\n\n\n \n The ID of the plate editor. Useful only when nesting editors. Default is using the closest editor id.\n \n boolean\" optional>\n Equality function to determine whether the result of the selector function has changed. Default is `(a, b) => a === b`.\n \n\n\n\n The return value of the selector function.\n\n\n\n### `useEditorState`\n\nGet the Plate editor reference with re-rendering.\n\n\n\n \n The ID of the plate editor. Default is using the closest editor id.\n \n\n\n\n The editor reference.\n\n\n\n### `useEditorComposing`\n\nGet the editor's `composing` state.\n\n\n\n \n The ID of the plate editor.\n \n\n\n Whether the editor is composing.\n\n\n\n### `useEditorReadOnly`\n\nGet the editor's `readOnly` state.\n\n\n \n The ID of the plate editor.\n \n\n\n Whether the editor is read-only.\n\n\n\n### `useEditorMounted`\n\nGet the editor's `isMounted` state.\n\n\n\n \n The ID of the plate editor.\n \n\n\n Whether the editor is mounted.\n\n\n\n### `useEditorSelection`\n\nGet the editor's selection. Memoized so it does not re-render if the range is the same.\n\n\n\n \n The ID of the plate editor.\n \n\n\nThe current selection in the editor.\n\n\n\n### `useEditorVersion`\n\nGet the version of the editor value. That version is incremented on each editor change.\n\n\n\n \n The ID of the plate editor.\n \n\n\nThe current version of the editor value.\n\n \n\n### `useSelectionVersion`\n\nGet the version of the editor selection. That version is incremented on each selection change (the range being different).\n\n\n\n \n The ID of the plate editor.\n \n\n\nThe current version of the editor selection.\n\n\n\n### `useSelectionCollapsed`\n\n\n\nWhether the current selection is collapsed.\n\n\n\n### `useSelectionExpanded`\n\n\n\nWhether the current selection is expanded.\n\n\n\n### `useSelectionWithinBlock`\n\n\n\nWhether the current selection is within a single block.\n\n\n\n### `useSelectionAcrossBlocks`\n\n\n\nWhether the current selection spans across multiple blocks.\n\n\n\n### `useSelectionFragment`\n\nReturns the fragment of the current selection, optionally unwrapping structural nodes.\n\n\n\n The fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.\n\n\n\n### `useSelectionFragmentProp`\n\nReturns a prop value derived from the current selection fragment.\n \n\n\n\nThe key of the property to extract from each node.\n\n\nThe default value to return if no valid prop is found.\n\n any\" optional>\nCustom function to extract the prop value from a node.\n\n\nDetermines how to traverse the fragment:\n- 'all': Check both block and text nodes\n- 'block': Only check block nodes\n- 'text': Only check text nodes\n \n- **Default**: `'block'`\n\n\n\n\nA value derived from the fragment nodes, or undefined if no consistent value is found across the specified nodes.\n\n\n\n### `useNodePath`\n\nReturns the path of a node in the editor.\n\n\n\n \n The node to find the path for.\n \n\n\n\n A memoized Path array representing the location of the node in the editor's tree structure.\n\n\n\n### `usePath`\n\nGet the memoized path of the closest element.\n\n\n\n \n The key of the plugin to get the path for.\n \n\n\n\n The path of the element, or `undefined` if used outside of a node component's context.\n\n \n\n### `usePluginOption`\n\nHook to access plugin options from the plugin store. For usage inside ``.\n\n\n\n \n The plugin to get options from.\n \n | InferSelectors) | 'state'\">\n The key of the option or selector to access.\n \n \n Additional arguments:\n - For selectors: The selector parameters\n - Last argument can be an equality function `(a: T, b: T) => boolean`\n \n\n\n\n The value of the option or selector result:\n - For 'state': Returns the entire state object\n - For selector keys: Returns the selector's return value\n - For option keys: Returns the option value\n\n\n```tsx\n// Access a simple option\nconst value = usePluginOption(plugin, 'value');\n// Access a selector with parameters\nconst doubleValue = usePluginOption(plugin, 'doubleValue', 2);\n// Access with equality function\nconst value = usePluginOption(plugin, 'value', (a, b) => a === b);\n// Access entire state\nconst state = usePluginOption(plugin, 'state');\n```\n\n\n\n### `useEditorPluginOption`\n\nHook to access plugin options from the plugin store. For usage outside ``.\n\n\n\n \n The editor instance.\n \n \n The plugin to get options from.\n \n | InferSelectors) | 'state'\">\n The key of the option or selector to access.\n \n \n Additional arguments:\n - For selectors: The selector parameters\n - Last argument can be an equality function `(a: T, b: T) => boolean`\n \n\n\n\n The value of the option or selector result:\n - For 'state': Returns the entire state object\n - For selector keys: Returns the selector's return value\n - For option keys: Returns the option value\n\n\n```tsx\n// Access a simple option\nconst value = useEditorPluginOption(editor, plugin, 'value');\n// Access a selector with parameters\nconst doubleValue = useEditorPluginOption(editor, plugin, 'doubleValue', 2);\n// Access with equality function\nconst value = useEditorPluginOption(editor, plugin, 'value', (a, b) => a === b);\n// Access entire state\nconst state = useEditorPluginOption(editor, plugin, 'state');\n```\n\n\n\n### `useElement`\n\nGet the element by plugin key.\n\n\n\n \n The key of the plugin to get the element for.\n - **Default:** `'element'`\n \n\n\n\n The element of type `T extends TElement`, or an empty object if used outside of a node component's context.\n\n\n\n## Core plugins\n\n### `DebugPlugin`\nProvides debugging capabilities with configurable log levels and error handling. \n\nSee [Debugging](/docs/debugging) for more details.\n\n### `SlateExtensionPlugin & SlateReactExtensionPlugin`\nExtend core apis and improve default functionality.\n\n`SlateExtensionPlugin` exposes `editor.api.isElementStateEmpty(element)`. It\nchecks the element's own props, not its text content. By default, only `type`\nand props claimed by plugins through `node.isMetadataProp` are ignored; any other\nprop means the element carries state. `NodeIdPlugin` uses `node.isMetadataProp` for\nthe configured NodeId key.\n\n```tsx\neditor.api.isElementStateEmpty({\n children: [{ text: '' }],\n type: 'p',\n}); // true\n\neditor.api.isElementStateEmpty({\n children: [{ text: '' }],\n listStyleType: 'disc',\n type: 'p',\n}); // false\n\nconst CustomMetadataPlugin = createSlatePlugin({\n key: 'customMetadata',\n node: {\n isMetadataProp: ({ key }) => key === 'customId',\n },\n});\n```\n\n### `DOMPlugin & ReactPlugin`\nIntegrates React-specific functionality into the editor.\n\n### `HistoryPlugin`\nEnables undo and redo functionality for the editor.\n\n### `InlineVoidPlugin`\nManages inline and void elements in the editor.\n\n### `ParserPlugin`\nHandles parsing of content for the editor.\n\n### `LengthPlugin`\nEnforces a maximum length for the editor content.\n\n### `HtmlPlugin`\nEnables HTML serialization and deserialization.\n\n### `AstPlugin`\nHandles Abstract Syntax Tree (AST) operations for the editor.\n\n### `ParagraphPlugin`\nProvides paragraph formatting functionality.\n\n### `EventEditorPlugin`\nManages editor events such as focus and blur.\n\n## Utils\n\n### `isType`\n\nChecks whether a node matches the provided type.\n\n\n\n \">\n The editor in which the node is present.\n \n \n The node to be checked.\n \n \n The type or types to match the node against. Can be a string or an array of\n strings.\n \n\n\n A boolean indicating whether the node's type matches the provided type or\n types.\n\n\n\n## Components\n\n### ``\n\nGeneric component for rendering an element.\n\n\n\n \n The CSS class to apply to the component.\n \n \n The editor instance. Also available using `useEditorRef` hook.\n \n \n The element node. Also available using `useElement` hook.\n \n \n The path of the element in the editor tree. Also available using `usePath` hook.\n \n \">\n Attributes of the element to be spread on the top-level element.\n \n \n Always set to `'element'`.\n \n \n \n \n \n The reference to the element. If using your own reference, merge it with this one.\n \n \n \n \n Necessary for rendering the node children.\n \n \n The component type to render as.\n - **Default:** `'div'`\n \n\n\n\n### ``\n\nGeneric component for rendering a leaf.\n\n\n\n \n The CSS class to apply to the component.\n \n \n The editor context.\n \n \n Necessary for rendering the node children.\n \n \n The leaf node.\n \n \n The text node.\n \n \">\n Attributes of the leaf to be spread on the top-level element.\n \n \n Always set to `true`.\n \n \n \n \n The component type to render as.\n - **Default:** `'span'`\n \n\n\n\n### ``\n\nGeneric component for rendering text.\n\n\n\n \n The CSS class to apply to the component.\n \n \n The text node.\n \n \">\n Attributes of the text to be spread on the top-level element.\n \n \n Necessary for rendering the node children.\n \n \n The component type to render as.\n - **Default:** `'span'`\n \n\n\n",
"type": "registry:file",
"target": "content/docs/plate/api/core.mdx"
}
],
"type": "registry:file"
}