{
"$schema": "https://ui.shadcn.com/schema/registry-item.json",
"name": "api-slate-editor-transforms-docs",
"title": "Editor Transforms",
"description": "API reference for editor transformation operations in Plate.",
"files": [
{
"path": "../../content/docs/api/slate/editor-transforms.mdx",
"content": "---\ntitle: Editor Transforms\ndescription: API reference for editor transformation operations in Plate.\n---\n\nTransforms are helper functions that manipulate a Plate document.\n\n## Node Operations\n\n### `duplicateNodes`\n\nDuplicates nodes at a location and inserts them after that location.\n\n\n\n \n `insertNodes` options.\n \n \n Location to duplicate from and insert after. Defaults to selection.\n \n \n If true, duplicates blocks above location. Ignored if `nodes` provided.\n \n \n Specific nodes to duplicate. Takes precedence over `block`.\n \n\n\n\n### `insertFragment`\n\nInsert a fragment of nodes at a location.\n\n\n\n \n Fragment of nodes to insert.\n \n \n\n\n\n \n Location to insert at. Defaults to selection.\n \n \n Whether range is hanging.\n \n \n Allow insertion in void nodes.\n \n\n\n\n### `insertNode`\n\nInsert a single node atomically.\n\n\n\n \n Node to insert.\n \n \n\n\n\n### `insertNodes`\n\nInsert one or more nodes atomically.\n\n\n\n \n Node(s) to insert.\n \n \n\n\n\n \n Common query options.\n \n \n \n \n Insert after the current block if `removeEmpty` caused it to be removed.\n \n \n Remove the current block if empty. Defaults to removing an empty paragraph, but can be customized.\n \n \n Select inserted nodes.\n \n \n Allow insertion in void nodes.\n \n\n\n\n### `liftNodes`\n\nLift nodes at the specified location upwards in the document tree. If necessary, the parent node is split.\n\n\n\n \n \n \n\n\n\n### `mergeNodes`\n\nMerge a node at the specified location with the previous node at the same depth. Resulting empty container nodes are removed.\n\n\n\n \n \n\n\n\n### `moveNodes`\n\nMove the nodes from an origin to a destination.\n\n\n\n \n \n Destination path.\n \n \n Move only children of the node at the location.\n \n \n Start index of the children to move. Default is 0.\n \n \n \n\n\n\n### `removeNodes`\n\nRemove nodes at a location.\n\n\n\n \n \n When true, remove all children of the node at the specified location.\n \n \n \n Remove the previous empty block if it exists.\n \n \n \n\n\n\n### `replaceNodes`\n\nReplace nodes at a location with new nodes.\n\n\n\n \n The new node(s) to insert.\n \n \n\n\n\n \n `insertNodes` options.\n \n \n Replace all children of the node at the specified location instead of the node itself.\n \n \" optional>\n Options for removing nodes before the replacement.\n \n\n\n\n### `reset`\n\nReset the editor state including history, selection and children.\n\n\n\n \n `replaceNodes` options.\n \n \n When true, only reset the children without clearing history/operations.\n \n\n\n\n### `setNodes`\n\nSet properties on nodes.\n\n\n\n >\">\n Properties to set. Use `undefined` to unset.\n \n \n\n\n\n \n , node: Partial) => boolean\" optional />\n \n \n When true, only apply to text nodes in non-void or markable void nodes.\n \n , node: Partial) => object\" optional />\n \n \n \n\n\n\n### `splitNodes`\n\nSplit nodes at a location.\n\n\n\n \n \n \n \n \n\n\n\n### `toggleBlock`\n\nToggle the block type at a location.\n\n\n\n \n The block type to toggle.\n \n \n\n\n\n \n Options to pass to `setNodes`.\n \n \n The default block type when untoggling. Defaults to paragraph.\n \n \n Options for determining if the block is active.\n \n \n If true, toggles wrapping with `type`. Otherwise, sets the block type directly.\n \n\n\n\n### `unsetNodes`\n\nRemove properties from nodes.\n\n\n\n \n Property key(s) to remove.\n \n \n\n\n\n \n \n \n \n \n\n\n\n### `unwrapNodes`\n\nUnwrap a node at a location. If necessary, the parent node is split.\n\n\n\n \n \n \n \n \n\n\n\n### `wrapNodes`\n\nWrap nodes at a location in the `element` container.\n\n\n\n \n The wrapper element.\n \n \n\n\n\n \n \n When true, wrap all children into a single container element.\n \n \n \n \n \n\n\n\n## Text Operations\n\n### `delete`\n\nDelete text at a location.\n\n\n\n \n \n Number of characters (or other unit) to delete. Default is 1.\n \n \n \n If true, delete backward.\n \n \n Unit to delete by.\n \n \n\n\n\n### `deleteBackward`\n\nDelete text backward.\n\n\n\n \n Defaults to `'character'`.\n \n\n\n\n### `deleteForward`\n\nDelete text forward.\n\n\n\n \n Defaults to `'character'`.\n \n\n\n\n### `deleteFragment`\n\nDelete a fragment of nodes.\n\n\n\n \n Direction to delete.\n \n\n\n\n### `insertText`\n\nInsert text at a location, optionally with marks. The behavior depends on the provided options:\n\n1. If `at` is specified in options, inserts at that location regardless of selection\n2. Otherwise, if there's a selection:\n - If `marks` is true (default) and editor has marks, inserts text with those marks\n - If no marks, inserts plain text\n3. If neither `at` nor selection exists, no text is inserted\n\n\n\n \n Text to insert.\n \n \n\n\n\n \n Location to insert text at. Takes precedence over current selection.\n \n \n Whether to allow insertion in void nodes.\n \n \n - **Default:** `true`\n When true and editor has marks, the inserted text will include those marks.\n When false, inserts plain text without marks.\n \n\n\n\n### `insertBreak`\n\nInsert a block break at the current selection.\n\n### `insertSoftBreak`\n\nInsert a soft break at the current selection. A soft break is a new line in the current block.\n\n### `deselect`\n\nUnset the selection.\n\n### `move`\n\nMove the selection's point forward or backward.\n\n\n\n \n How many units to move. Defaults to 1.\n \n \n Defaults to `'character'`.\n \n \n Move backward if true.\n \n \n Which edge to move.\n \n\n\n\n## Mark Operations\n\n### `addMark`\n\nAdd a custom property to the leaf text nodes within non-void nodes or void nodes that `editor.markableVoid()` allows in the current selection. If the selection is currently collapsed, the marks will be added to the `editor.marks` property instead, and applied when text is inserted next.\n\n\n\n \n Mark key to add.\n \n \n Value for the mark.\n \n\n\n\n### `addMarks`\n\nAdd multiple marks to the current selection.\n\n```ts\neditor.tf.addMarks({ bold: true, italic: true })\neditor.tf.addMarks({ bold: subscript }, { remove: 'superscript' })\neditor.tf.addMarks({ bold: true }, { remove: ['italic', 'underline'] })\n```\n\n\n\n \">\n Key-value pairs of mark props.\n \n \n\n\n\n \n Mark keys to remove first. For mutually exclusive marks, e.g. subscript/superscript.\n \n\n\n\n### `removeMark`\n\nRemove a mark from text in the selection.\n\n\n\n \n Mark key to remove.\n \n\n\n\n### `removeMarks`\n\nRemove marks from text nodes in the current selection or from `editor.marks`. The behavior depends on the selection state and options:\n\n1. If selection is expanded or is in a markable void node:\n - Remove specified mark keys from text nodes\n2. If selection is collapsed and no custom range provided:\n - Remove specified keys from `editor.marks`\n - If no keys specified, clear all marks from `editor.marks`\n3. If custom range provided (`at` option):\n - Only remove marks from text nodes in that range\n\n```ts\neditor.tf.removeMarks() // remove all marks\neditor.tf.removeMarks('bold') // remove the 'bold' mark\neditor.tf.removeMarks(['bold','italic'])\neditor.tf.removeMarks('bold', { at: range })\n```\n\n\n\n \n Mark key(s) to remove. If not provided and selection is collapsed, clears all marks from `editor.marks`.\n \n \n\n\n\n \n \n Custom range to remove marks from. Takes precedence over current selection.\n \n \n - **Default:** `true`\n Whether to trigger onChange when modifying editor.marks.\n \n \n Whether to split nodes when removing marks.\n \n boolean\" optional>\n Custom function to filter which nodes to remove marks from.\n \n \n Whether to allow removing marks from void nodes.\n \n\n\n\n### `toggleMark`\n\nToggle a mark on or off in the current selection. If the mark exists, removes it. If it doesn't exist:\n1. Removes any specified marks in the `remove` option \n2. Adds the mark with value `true`\n\n```ts\neditor.tf.toggleMark('bold') // Toggle bold on/off\neditor.tf.toggleMark('subscript', { remove: 'superscript'}) // Remove superscript before adding subscript\n```\n\n\n\n \n The mark key to toggle.\n \n \n\n\n\n \n Mark key(s) to remove before adding the mark. Useful for mutually exclusive marks like subscript/superscript.\n The specified mark key is always removed in addition to these marks.\n \n\n\n\n## Selection\n\n### `collapse`\n\nCollapse the selection to a point.\n\n\n\n \n Edge to collapse to. Defaults to `'anchor'`.\n \n\n\n\n### `deselect`\n\nUnset the current selection.\n\n### `move`\n\nMove the selection's point.\n\n\n\n \n Defaults to 1.\n \n \n Defaults to `'character'`.\n \n \n If true, move backward.\n \n \n Which edge to move.\n \n\n\n\n### `select`\n\nSet the selection to a new value specified by `at`. When a selection already exists, this method just calls `setSelection`.\n\n```ts\neditor.tf.select(at)\neditor.tf.select(at, { edge: 'end' })\neditor.tf.select(at, { edge: 'start' })\n```\n\n\n\n \n Location to select.\n \n \n\n\n\n \n Select the start or end edge above `at`.\n \n \n Focus the editor before selecting.\n \n \n Select the start of the next sibling.\n \n \n Select the end of the previous sibling.\n \n\n\n\n### `setPoint`\n\nSet new properties on one of the selection's points.\n\n\n\n \">\n Point properties to update.\n \n \n\n\n\n \n Which edge of the selection to set.\n \n\n\n\n### `setSelection`\n\nSet new properties on an active selection. Since the value is a `Partial`, this method can only handle updates to an existing selection. If there is no active selection the operation will be void. Use `select` if you'd like to create a selection when there is none.\n\n\n\n \">\n A partial range to update existing selection properties.\n \n\n\n\n## DOM Operations\n\n### `blur`\n\nBlur the editor.\n\n### `deselectDOM`\n\nDeselect the editor's DOM selection in addition to `deselect`.\n\n### `focus`\n\nFocus the editor.\n\n```ts\neditor.tf.focus()\neditor.tf.focus({ edge: 'end' })\neditor.tf.focus({ edge: 'endEditor' })\n```\n\n\n\n \n Select this location before focusing.\n \n \n Focus at the edge of the location or the editor.\n \n \n Number of attempts to refocus.\n \n\n\n\n### `insertData`\n\nInsert data from a `DataTransfer` into the editor. Calls:\n\n1. `insertFragmentData(editor: ReactEditor, data: DataTransfer)`\n2. `insertTextData(editor: ReactEditor, data: DataTransfer)`\n\n\n\n \n Data to insert from clipboard or drag event.\n \n\n\n\n### `insertFragmentData`\n\nInsert fragment data from a `DataTransfer` into the editor.\n\n\n\n \n Data to parse as fragment.\n \n\n\n\n\n\n### `insertTextData`\n\nInsert text data from a `DataTransfer` into the editor.\n\n\n\n \n Text data to insert.\n \n\n\n\n\n\n### `setFragmentData`\n\nSets data from the currently selected fragment on a `DataTransfer`.\n\n\n\n \n DataTransfer to store the fragment.\n \n\n\n\n## History Operations\n\n### `redo`\n\nRedo to the next saved state.\n\n### `undo`\n\nUndo to the previous saved state.\n\n### `setSplittingOnce`\n\n\n\n \n Whether the next operation should split into a new batch in history.\n \n\n\n\n### `withMerging`\n\nApply a series of changes inside a synchronous `fn`, These operations will\nbe merged into the previous history.\n\n\n\n void\">\n Batched changes to merge into the previous history point.\n \n\n\n\n### `withNewBatch`\n\nApply a series of changes inside a synchronous `fn`, ensuring that the first\noperation starts a new batch in the history. Subsequent operations will be\nmerged as usual.\n\n\n\n void\">\n Batched changes in a new history point.\n \n\n\n\n### `withoutMerging`\n\nApply a series of changes inside a synchronous `fn`, without merging any of\nthe new operations into previous save point in the history.\n\n\n\n void\">\n Changes not merged into any existing history point.\n \n\n\n\n### `withoutSaving`\n\nApply a series of changes inside a synchronous `fn`, without saving any of\ntheir operations into the history.\n\n\n\n void\">\n Changes not saved into history at all.\n \n\n\n\n## Core Operations\n\n### `apply`\n\nApply an operation in the editor.\n\n\n\n \">\n Operation to apply.\n \n\n\n\n### `normalizeNode`\n\nNormalize a node according to the editor's schema.\n\n\n\n \">\n The node entry to normalize.\n \n \n\n\n\n \n The triggering operation.\n \n\n\n\n### `normalize`\n\nNormalize dirty nodes in the editor.\n\n\n\n \n When true, forcibly re-normalize all nodes.\n \n \n\n\n\n### `withoutNormalizing`\n\nCall a function, deferring normalization until after it completes.\n\n\n\n void\">\n A synchronous function to execute without normalization in between operations.\n \n\n\n\n True if normalization was performed afterwards.\n\n\n\n## Keyboard Shortcuts\n\n### `moveLine`\n\nHandle `ArrowUp` and `ArrowDown` keyboard events.\n\n\n\n \n - `reverse: true` for `ArrowUp`\n - `reverse: false` for `ArrowDown`\n \n\n\n\n Return `true` to prevent default browser behavior, `false` to allow it.\n\n\n\n**Default behavior:** Returns `false` (allows Plate's default line movement).\n\n**Usage:**\n```ts\nconst plugin = createPlatePlugin({\n key: 'myPlugin',\n}).overrideEditor(() => ({\n transforms: {\n moveLine: ({ reverse }) => {\n // Custom line movement logic\n if (reverse) {\n // Handle ArrowUp\n } else {\n // Handle ArrowDown \n }\n return true; // Prevent default\n },\n },\n}));\n```\n\n### `tab`\n\nHandle `Tab` and `Shift+Tab` keyboard events.\n\n\n\n \n - `reverse: false` for `Tab`\n - `reverse: true` for `Shift+Tab`\n \n\n\n\n Return `true` to prevent default browser behavior, `false` to allow it.\n\n\n\n**Default behavior:** Returns `false` (allows default browser tab navigation).\n\n**Usage:**\n```ts\nconst plugin = createPlatePlugin({\n key: 'myPlugin',\n}).overrideEditor(() => ({\n transforms: {\n tab: ({ reverse }) => {\n if (reverse) {\n // Handle Shift+Tab (usually outdent)\n editor.tf.outdent();\n } else {\n // Handle Tab (usually indent)\n editor.tf.indent();\n }\n return true; // Prevent default\n },\n },\n}));\n```\n\n### `selectAll`\n\nHandle `Cmd+A` / `Ctrl+A` keyboard events.\n\n\n\n Return `true` to prevent default browser behavior, `false` to allow it.\n\n\n\n**Default behavior:** Returns `false` (allows default browser select all).\n\n**Usage:**\n```ts\nconst plugin = createPlatePlugin({\n key: 'myPlugin',\n}).overrideEditor(() => ({\n transforms: {\n selectAll: () => {\n // Custom select all logic\n const blockEntry = editor.api.block();\n if (blockEntry) {\n editor.tf.select(blockEntry[1]);\n return true; // Prevent default\n }\n return false; // Allow default\n },\n },\n}));\n```\n\n### `escape`\n\nHandle `Escape` keyboard events.\n\n\n\n Return `true` to prevent default browser behavior, `false` to allow it.\n\n\n\n**Default behavior:** Returns `false` (allows default browser escape handling).\n\n**Usage:**\n```ts\nconst plugin = createPlatePlugin({\n key: 'myPlugin',\n}).overrideEditor(() => ({\n transforms: {\n escape: () => {\n // Custom escape logic (e.g., exit special mode)\n if (editor.api.inSpecialMode()) {\n editor.tf.exitSpecialMode();\n return true; // Prevent default\n }\n return false; // Allow default\n },\n },\n}));\n```\n",
"type": "registry:file",
"target": "content/docs/plate/api/slate/editor-transforms.mdx"
}
],
"type": "registry:file"
}