{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "api-core-plate-plugin-docs",
"title": "Plate Plugin",
"description": "API reference for Plate plugins.",
"files": [
{
"path": "../../content/docs/api/core/plate-plugin.mdx",
"content": "---\ntitle: Plate Plugin\ndescription: API reference for Plate plugins.\n---\n\nPlate plugins are objects passed to `Plate` [plugins](/docs/api/core/plate-components#plugins) prop.\n\n## Plugin Properties\n\n\n\n\nUnique identifier used by Plate to store the plugins by key in `editor.plugins`.\n\n\n\">\nAn object of API functions provided by the plugin. These functions are accessible via `editor.api[key]`.\n\n\n\">\nTransform functions provided by the plugin that modify the editor state. These are accessible via `editor.tf[key]`.\n\n\n\">\nExtended properties used by the plugin as options.\n\n\n void } & Record\">\nEvent handlers for various editor events.\n\n\n void\" optional>\nCalled whenever the editor content changes.\n\n\nCalled whenever a node operation occurs (insert, remove, set, merge, split, move).\n\n```ts\ntype OnNodeChange = (ctx: PlatePluginContext & {\n node: Descendant;\n operation: NodeOperation;\n prevNode: Descendant;\n}) => HandlerReturnType;\n```\n\n**Parameters:**\n- `node`: The node after the operation\n- `operation`: The node operation that occurred\n- `prevNode`: The node before the operation\n\n**Note:** For `insert_node` and `remove_node` operations, both `node` and `prevNode` contain the same value to avoid null cases.\n\n\nCalled whenever a text operation occurs (insert or remove text).\n\n```ts\ntype OnTextChange = (ctx: PlatePluginContext & {\n node: Descendant;\n operation: TextOperation;\n prevText: string;\n text: string;\n}) => HandlerReturnType;\n```\n\n**Parameters:**\n- `node`: The parent node containing the text that changed\n- `operation`: The text operation that occurred (`insert_text` or `remove_text`)\n- `prevText`: The text content before the operation\n- `text`: The text content after the operation\n\n\n\n\n\nDefines how the plugin injects functionality into other plugins or the editor.\n\n\n\" optional>\nProperties used by Plate to inject props into any node component.\n\n\n\n\nAn array of plugin keys to exclude from node prop injection.\n\n\n\nAn array of plugin keys. Node prop injection will be excluded for any nodes that are descendants of elements with these plugin types.\n\n\nIf true, only matches block elements. Used to restrict prop injection to block-level nodes.\n\n\n\nIf true, only matches element nodes. Used to restrict prop injection to element nodes.\n\n\nIf true, only matches leaf nodes. Used to restrict prop injection to leaf nodes.\n\n\nMaximum nesting level for node prop injection. Nodes deeper than this level will not receive injected props.\n\n>\" optional>\nProperty that can be used by a plugin to allow other plugins to inject code.\n\n\nA function that returns a plugin config to be injected into other plugins `inject.plugins` specified by targetPlugins.\n\n\nPlugin keys used by `InjectNodeProps` and the `targetPluginToInject` function.\n\n- **Default:** `[ParagraphPlugin.key]`\n\n\n\n\n\nDefines the node-specific configuration for the plugin.\n\n\n\nIndicates if this plugin's nodes can be rendered as decorated leaf. Set to false to render node component only once per text node.\n\n- **Default:** `true`\n\n\nIndicates if this plugin's nodes should be rendered as elements.\n\n\nIndicates if this plugin's elements should be treated as inline.\n\n\nIndicates if this plugin's nodes should be rendered as leaves.\n\n\nWhen `true`, indicates that the plugin's elements are primarily containers for other content. This property is typically used by fragment queries to unwrap the container nodes.\n\n\nDefines the selection behavior at the boundaries of nodes. See [Plugin Rules](/docs/plugin-rules#rulesselection).\n\n- `'default'`: Uses Slate's default behavior\n- `'directional'`: Selection affinity is determined by the direction of cursor movement. Maintains inward or outward affinity based on approach\n- `'outward'`: Forces outward affinity. Typing at the edge of a mark will not apply the mark to new text\n- `'hard'`: Creates a 'hard' edge that requires two key presses to move across. Uses offset-based navigation\n\n- **Default:** `undefined` (Slate's default behavior)\n\n\nIndicates if this plugin's void elements should be markable.\n\n\nIndicates if this plugin's nodes should be selectable.\n\n- **Default:** `true`\n\n\nIndicates whether this element enforces strict sibling type constraints. Set to `true` when the element only allows specific siblings (e.g., `td` can only have `td` siblings, `column` can only have `column` siblings) and prevents standard text blocks like paragraphs from being inserted as siblings.\n\nUsed by exit break functionality to determine appropriate exit points in nested structures. See [Exit Break](/docs/exit-break).\n\n- **Default:** `false`\n\n\nAction when Enter is pressed in an empty block. See [Plugin Rules](/docs/plugin-rules).\n\n- `'default'`: Default behavior\n- `'reset'`: Reset block to default paragraph type\n- `'exit'`: Exit the current block\n- `'lift'`: Lift the current block out of the nearest matching ancestor\n- `'deleteExit'`: Delete backward then exit\n\n\nAction when Enter is pressed at the end of an empty line. This is typically used with `rules.break.default: 'lineBreak'`. See [Plugin Rules](/docs/plugin-rules).\n\n- `'default'`: Default behavior\n- `'exit'`: Exit the current block\n- `'deleteExit'`: Delete backward then exit\n\n\nDefault action when Enter is pressed. Defaults to splitting the block. See [Plugin Rules](/docs/plugin-rules).\n\n- `'default'`: Default behavior\n- `'exit'`: Exit the current block\n- `'lineBreak'`: Insert newline character\n- `'deleteExit'`: Delete backward then exit\n\n\nIf true, the new block after splitting will be reset to the default type. See [Plugin Rules](/docs/plugin-rules).\n\n\nAction when Backspace is pressed at the start of the block. This applies whether the block is empty or not. See [Plugin Rules](/docs/plugin-rules).\n\n- `'default'`: Default behavior\n- `'lift'`: Lift the current block out of the nearest matching ancestor\n- `'reset'`: Reset block to default paragraph type\n\n\nAction when Backspace is pressed and the block is empty. See [Plugin Rules](/docs/plugin-rules).\n\n- `'default'`: Default behavior\n- `'reset'`: Reset block to default paragraph type\n\n\nFunction to determine if this plugin's rules should apply to a node. Used to override behavior based on node properties beyond just type matching.\n\n**Default:** `type === node.type`\n\n**Example:** `matchRules: ({ node }) => Boolean(node.listStyleType)`\n\nExample: List plugin sets `match: ({ node }) => !!node.listStyleType` to override paragraph behavior when the paragraph is a list item.\n\n\n\nWhether to remove the node when it's empty during merge operations. See [Plugin Rules](/docs/plugin-rules).\n\n- **Default:** `false`\n\n\nWhether to remove nodes with empty text during normalization. See [Plugin Rules](/docs/plugin-rules).\n\n- **Default:** `false`\n\n\nIndicates if this plugin's elements should be treated as void.\n\n\nSpecifies the type identifier for this plugin's nodes. \n\n- **Default:** `plugin.key`\n\n\nReact component used to render this plugin's nodes.\n\n>\" optional>\nOverride `data-slate-leaf` element attributes.\n\n>\" optional>\nOverride node attributes.\n\n>\" optional>\nOverride `data-slate-node=\"text\"` element attributes.\n\n\n\n\n\nAllows overriding components and plugins by key.\n\n\n\" optional>\nReplace plugin `NodeComponent` by key.\n\n>>\" optional>\nExtend `PlatePlugin` by key.\n\n>\" optional>\nEnable or disable plugins.\n\n\n\n\n>>\">\nDefines how the plugin parses content.\n\n\n\nDefines serializers and deserializers for various formats.\n\n\n>; serializer?: HtmlSerializer> }>\" optional>\nHTML parser configuration.\n\n> }>\" optional>\nHTML React serializer configuration.\n\n\n\n\n\nDefines how the plugin renders components.\n\n\n\nComponent rendered above the Editable component but inside the Slate wrapper.\n\n>\" optional>\nCreate a function that generates a parent React node for all other plugins' node components.\n\n\nComponent rendered above the Slate wrapper.\n\n\nRenders a component after the Editable component.\n\n\nRenders a component before the Editable component.\n\n>\" optional>\nCreate a function that generates a React node below all other plugins' node React node, but above their children.\n\n) => React.ReactNode\" optional>\nRenders a component after the direct children of the root element. This differs from `belowNodes` in that it's the direct child of `PlateElement` rather than wrapping the children that could be nested. This is useful when you need components relative to the root element.\n\n\nRenders a component below leaf nodes when `isLeaf: true` and `isDecoration: false`. Use `render.node` instead when `isDecoration: true`.\n\n\nRenders a component for:\n- Elements nodes if `isElement: true`\n- Below text nodes if `isLeaf: true` and `isDecoration: false`\n- Below leaf if `isLeaf: true` and `isDecoration: true`\n\n\nSpecifies the HTML tag name to use when rendering the node component. Only used when no custom `component` is provided for the plugin.\n\n- **Default:** `'div'` for elements, `'span'` for leaves\n\n\n\n\n\n\nDefines keyboard shortcuts for the plugin.\n\n\n\">\nZustand store for managing plugin options.\n\n\n\nAn array of plugin keys that this plugin depends on.\n\n\n\nEnables or disables the plugin. Used by Plate to determine if the plugin should be used.\n\n\n\nRecursive plugin support to allow having multiple plugins in a single plugin.\n\n\n\nDefines the order in which plugins are registered and executed.\n\n- **Default:** `100`\n\n\n>\" optional>\nProperty used by Plate to decorate editor ranges.\n\n\n>\" optional>\nFunction to extend the editor instance. Used primarily for integrating legacy Slate plugins that need direct editor mutation. Only one `extendEditor` is allowed per plugin.\n\n```ts\nextendEditor: ({ editor }) => {\n // Example: Integrating a legacy Slate plugin\n return withYjs(editor);\n}\n```\n\n\n void\" optional>\nHook called when the editor is initialized.\n\n\n\nConfigures which plugin functionalities should only be active when the editor is not read-only.\n\nCan be either a boolean or an object configuration:\n\n```ts\ntype EditOnlyConfig = {\n render?: boolean; // default: true\n handlers?: boolean; // default: true\n inject?: boolean; // default: true\n transformInitialValue?: boolean; // default: false\n}\n```\n\nWhen set to `true` (boolean):\n- `render`, `handlers`, and `inject.nodeProps` are only active when editor is not read-only\n- `transformInitialValue` remains active regardless of read-only state\n\nWhen set to an object:\n- Each property can be individually configured\n- Properties default to being edit-only (`true`) except `transformInitialValue` which defaults to always active (`false`)\n- Set a property to `false` to make it always active regardless of read-only state\n- For `transformInitialValue`, set to `true` to make it edit-only\n\nExamples:\n```ts\n// All features (except transformInitialValue) are edit-only\neditOnly: true\n\n// transformInitialValue is edit-only, others remain edit-only by default\neditOnly: { transformInitialValue: true }\n\n// render is always active, others follow default behavior\neditOnly: { render: false }\n```\n\n\n\n\n## Plugin Methods\n\n\n\n PlatePluginConfig)) => PlatePlugin\">\nCreates a new plugin instance with updated options.\n\n```ts\n(config: PlatePluginConfig, InferApi, InferTransforms> | ((ctx: PlatePluginContext) => PlatePluginConfig, InferApi, InferTransforms>)) => PlatePlugin\n```\n\n\n | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin\">\nCreates a new plugin instance with additional configuration.\n\n```ts\n(extendConfig: Partial | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin\n```\n\n\n | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin\">\nExtends an existing nested plugin or adds a new one if not found. Supports deep nesting.\n\n```ts\n(key: string, extendConfig: Partial | ((ctx: PlatePluginContext) => Partial)) => PlatePlugin\n```\n\n\n\nSets or replaces the component associated with a plugin.\n\n```ts\n(component: NodeComponent) => PlatePlugin\n```\n\n\n\nCreates a new plugin instance with overridden editor methods. Provides access to original methods via `tf` and `api` parameters. Can be called multiple times to layer different overrides.\n\n```ts\noverrideEditor(({ editor, tf: { deleteForward }, api: { isInline } }) => ({\n transforms: {\n // Override transforms\n deleteForward(options) {\n deleteForward(options);\n },\n },\n api: {\n // Override API methods\n isInline(element) {\n return isInline(element);\n },\n },\n})) => PlatePlugin\n```\n\n- Preferred method for modifying editor behavior\n- Type-safe access to original methods\n- Clean separation between transforms and API\n- Can be chained multiple times\n\n\n Record) => PlatePlugin\">\nExtends the plugin's API.\n\n```ts\n(api: (ctx: PlatePluginContext) => Record) => PlatePlugin\n```\n\n\n Record) => PlatePlugin\">\nExtends the editor's API with plugin-specific methods.\n\n```ts\n(api: (ctx: PlatePluginContext) => Record) => PlatePlugin\n```\n\n\n Record) => PlatePlugin\">\nExtends the plugin's transforms.\n\n```ts\n(transforms: (ctx: PlatePluginContext) => Record) => PlatePlugin\n```\n\n\n Record) => PlatePlugin\">\nExtends the editor's transforms with plugin-specific methods.\n\n```ts\n(transforms: (ctx: PlatePluginContext) => Record) => PlatePlugin\n```\n\n\n Record) => PlatePlugin\">\nExtends the plugin with selectors.\n\n```ts\n(options: (ctx: PlatePluginContext) => Record) => PlatePlugin\n```\n\n\n\n\n## Plugin Context\n\n\n\n\nThe current editor instance.\n\n\">\nThe current plugin instance.\n\n\nFunction to get a specific option value.\n\n\nFunction to get all options for the plugin.\n\n\nFunction to set a specific option value.\n\n\nFunction to set multiple options.\n\n\n\n\nFor more detailed information on specific aspects of Plate plugins, refer to the individual guides on [Plugin Configuration](/docs/plugin), [Plugin Methods](/docs/plugin-methods), [Plugin Context](/docs/plugin-context), [Plugin Components](/docs/plugin-components), and [Plugin Shortcuts](/docs/plugin-shortcuts).\n\n## Generic Types\n\n\n\n\nRepresents the plugin configuration. This type extends `PluginConfig` which includes `key`, `options`, `api`, and `transforms`.\n\n\n\n\nUsage example:\n\n```typescript\ntype MyPluginConfig = PluginConfig<\n 'myPlugin',\n { customOption: boolean },\n { getData: () => string },\n { customTransform: () => void }\n>;\n\nconst MyPlugin = createPlatePlugin({\n key: 'myPlugin',\n // plugin implementation\n});\n```\n",
"type": "registry:file",
"target": "content/docs/plate/api/core/plate-plugin.mdx"
}
],
"type": "registry:file"
}