4f:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 50:Tb8fa,--- title: Editor API description: API reference for the Editor API. --- The Editor API provides a set of helper functions for querying and manipulating the editor state. ## Common Options ### `At` A location reference in the editor. Can be either a Location or a Node. ```ts type At = TLocation | TNode ``` When a Node is passed, its path will be found using [`editor.api.findPath()`](/docs/api/slate/editor-api#findpath). This allows you to reference a location by either: - A [Location](/docs/api/slate/location) ([Path](/docs/api/slate/path), [Point](/docs/api/slate/point), or [Range](/docs/api/slate/range)) - A [Node](/docs/api/slate/node) Example: ```ts // Using a location editor.api.nodes({ at: [0, 0] }) // Path location editor.api.nodes({ at: { path: [0], offset: 0 } }) // Point location editor.api.nodes({ at: { anchor: point1, focus: point2 } }) // Range location // Using a node reference const node = editor.children[0] editor.api.nodes({ at: node }) // Will find node's path internally ``` ### Match A predicate for matching nodes. The predicate can be either: - A function that takes a `node` and its `path` and returns a `boolean` - An object where each key-value pair must match the node's properties - Values can be single values or arrays of values to match against Example: ```ts // Function predicate editor.api.nodes({ match: (node) => node.type === 'p' }) // Object predicate editor.api.nodes({ match: { type: 'p' } }) // Object predicate with multiple possible values editor.api.nodes({ match: { type: ['p', 'h1'] } }) ``` ### `QueryMode` Mode for querying nodes in a hierarchy. - `'all'` (default): Return all matching nodes - `'highest'`: In a hierarchy of nodes, only return the highest-level matching nodes - `'lowest'`: In a hierarchy of nodes, only return the lowest-level matching nodes Example: ```ts // Given this structure: // - blockquote (matches) // - paragraph (matches) // - text // mode: 'all' returns both blockquote and paragraph editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'all' }) // mode: 'highest' returns only blockquote editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'highest' }) // mode: 'lowest' returns only paragraph editor.api.nodes({ match: { type: ['blockquote', 'paragraph'] }, mode: 'lowest' }) ``` ### `QueryOptions` Common options for querying nodes in the editor. Where to start querying from. Defaults to current editor selection. Match block nodes. When true, only matches block elements. Match empty/non-empty nodes. - When true, matches only empty nodes - When false, matches only non-empty nodes Match the node by id. - When true, matches all nodes with an id - When string, matches nodes with that specific id Custom function or object to match nodes. - Function: `(node, path) => boolean` - Object: Key-value pairs that should match the node Match text nodes. When true, matches only text nodes. ## `editor.api` ### `above` Get the matching ancestor above a location in the document. Common query options. Query mode options. Whether to include void nodes in the search. A tuple containing the matching ancestor node and its path, or `undefined` if no match is found. ### `block` Get the block at a location or find the first block that matches options. Blocks are typically top-level nodes, so this is a common way to retrieve the ancestor block. ```ts editor.api.block() // Get block above selection editor.api.block({ above: true }) // Get block above selection editor.api.block({ at: [0, 0] }) // Get block at [0, 0] editor.api.block({ at: [0, 0], above: true }) // Get block at [0] editor.api.block({ highest: true }) // Get highest block at selection ``` Common query options for matching blocks. The location to query at. Defaults to current selection. Whether to ignore non-selectable nodes during traversal. Whether to traverse in reverse order. Whether to ensure the operation works universally across all nodes. If true, get the block above the location. Ignored if `at` is not a block path. If true, get the highest block at the location (root-level block). Query mode for matching blocks. Whether to include void nodes in the search. The matching block node entry or `undefined` if no match is found. ### `blocks` Returns all matching blocks. Common query options for matching blocks. The location to query at. Defaults to current selection. Whether to ignore non-selectable nodes during traversal. Whether to traverse in reverse order. Whether to ensure the operation works universally across all nodes. Query mode for matching blocks. Whether to include void nodes in the search. An array of matching block node entries. ### `edgeBlocks` Returns the edge blocks above a location (default: selection). Useful for retrieving the start and end block of a range. Common query options for matching blocks. The location to get edge blocks from. Defaults to current selection. Whether to ignore non-selectable nodes during traversal. Whether to traverse in reverse order. Whether to ensure the operation works universally across all nodes. Query mode for matching blocks. Whether to include void nodes in the search. A tuple of `[startBlock, endBlock]` above the location, or `null` if not found. ### `first` Get the first node at a location. The location to get the first node from. A tuple containing the first node and its path, or undefined if not found. ### `fragment` Get the fragment at a location or selection. The location to extract the fragment from. Defaults to current selection. Options for extracting and processing the fragment. The fragment at the location. ### `getFragment` Returns the fragment at the current selection. Used when cutting or copying, as an example, to get the fragment at the current selection. The location to get the fragment from. Defaults to current selection. The fragment at the current selection. ### `hasBlocks` Check if a node has block children. The element to check. True if the element has block children, false otherwise. ### `hasInlines` Check if a node has inline and text children. The element to check. True if the element has inline and text children, false otherwise. ### `hasMark` Check if mark is active at selection. The mark key to check. True if the mark is active at the current selection, false otherwise. ### `hasPath` Check if a path exists in the editor. The path to check. True if the path exists, false otherwise. ### `hasTexts` Check if a node has text children. The element to check. True if the element has text children, false otherwise. ### `isAt` Check if a location (point/range) is at a specific position. ```ts // For ranges: editor.api.isAt({ text: true }) // Check if range is in a single text node editor.api.isAt({ block: true }) // Check if range is in a single block editor.api.isAt({ blocks: true }) // Check if range is across multiple blocks editor.api.isAt({ start: true }) // Check if range starts at block start editor.api.isAt({ end: true }) // Check if range ends at block end // For points: editor.api.isAt({ word: true }) // Check relative to word boundaries editor.api.isAt({ start: true }) // Check if at start editor.api.isAt({ end: true }) // Check if at end ``` The location to check. Defaults to current selection. Check if range is in a single text node. Check if range is in a single block. Check if range is across multiple blocks. Check if at start position. Check if at end position. Check relative to word boundaries. True if the location matches all specified position criteria, false otherwise. ### `isCollapsed` Check if the selection is collapsed (start and end points are the same). True if the selection is collapsed, false otherwise. ### `isEdge` Check if a point is an edge of a location. The point to check. The location to check against. Defaults to current selection. True if the point is an edge of the location, false otherwise. ### `isEditorEnd` Check if selection is at editor end. True if the selection is at the editor end, false otherwise. ### `isEmpty` Check if an element is empty, accounting for void nodes. ```ts editor.api.isEmpty() // Check if editor is empty editor.api.isEmpty(at) // Check if nodes at location are empty editor.api.isEmpty(at, { after: true }) // Check if text after location is empty editor.api.isEmpty(at, { block: true }) // Check if block above location is empty ``` The location to check for emptiness. Defaults to current selection. Options for determining emptiness. Check if text after selection is empty. Check if the block above location is empty. ### `isEnd` Check if a point is the end point of a location. The point to check. The location to check against. Defaults to current selection. True if the point is the end point of the location, false otherwise. ### `isExpanded` Check if the selection is expanded (start and end points are different). True if the selection is expanded, false otherwise. ### `isNormalizing` Check if the editor is currently normalizing after each operation. True if the editor is currently normalizing, false otherwise. ### `isStart` Check if a point is the start point of a location. The point to check. The location to check against. Defaults to current selection. True if the point is the start point of the location, false otherwise. ### `isSelected` Check if a path is selected by the current selection. The path or range to check. Options for checking selection. Check if selection contains the entire path range. True if the path is selected, false otherwise. ### `leaf` Get the leaf text node at a location. The location to get the leaf from. Options for getting the leaf. The depth to traverse to find the leaf. Which edge of the location to get the leaf from (`'start' | 'end'`). A tuple containing the leaf text node and its path, or undefined if not found. ### `levels` Iterate through all levels at a location. This includes all ancestors up to the root editor node. Common query options for matching levels. Whether to traverse in reverse order (bottom-up vs. top-down). Whether to include void nodes in the traversal. A generator that yields tuples of [node, path] for each ancestor level. ### `last` Get the last node at a location. The location to get the last node from. Options for getting the last node. Get last node at this level (0-based). A tuple containing the last node and its path, or undefined if not found. ### `mark` Returns the selection mark value by key. The mark key. The mark value if it exists, null if not set, or undefined if multiple different values exist. ### `marks` Get the marks that would be added to text at the current selection. The marks at the current selection, or null if there are no marks. ### `next` Get the matching node in the branch of the document after a location. Common query options for matching nodes. The location to start searching from. Defaults to current selection. Query mode for matching nodes. Whether to include void nodes in the search. - `'after'`: Start from point after current location - `'child'`: Start from the first child of current path A tuple containing the next matching node and its path, or undefined if not found. ### `node` Get the node at a location or find the first node that matches options. The location to get a node from. Options for getting a node. The depth to traverse to find the node. Which edge of the location to get the node from. A tuple containing the matching node and its path, or undefined if not found. ### `nodes` Iterate through all nodes in the editor that match the given options. Common query options for matching nodes. Where to start iterating. Defaults to editor selection. Whether to ignore non-selectable nodes during traversal. Whether to traverse in reverse order. Whether to ensure the operation works universally across all nodes. - `'all'`: Return all matching nodes - `'highest'`: Return highest-level matching nodes - `'lowest'`: Return lowest-level matching nodes Whether to include void nodes in the search. A generator that yields tuples of [node, path] for each matching node. ### `parent` Get the parent node of a location. The location to get the parent from. Options for getting the parent node. Number of levels to traverse up to find the parent. Which edge of the location to get the parent from. A tuple containing the parent node and its path, or undefined if not found. ### `previous` Get the matching node in the branch of the document before a location. Common query options for matching nodes. The location to start searching from. Defaults to current selection. Query mode for matching nodes. Whether to include void nodes in the search. Whether to get the previous sibling node instead of any previous node. - `'before'`: Start from point before current location - `'parent'`: Start from parent of current location A tuple containing the previous matching node and its path, or undefined if not found. ### `prop` Get a property value from a list of nodes. Returns `undefined` if the property value is not consistent across all nodes. The list of nodes to get the property value from. The property key to get from the nodes. Default value to return if property is not found. Custom function to extract property value from a node. - `'all'`: Get property from all nodes - `'block'`: Get property from the first block node - `'text'`: Get property from the first text node The consistent property value across all nodes, or `undefined` if values differ. ### `string` Get the text string content of a location. The location to get text content from. Defaults to current selection. Options for getting text content. Whether to include text content from void nodes. The text content at the specified location. ### `void` Match a void node in the current branch of the editor. The location to search from. Defaults to current selection. Query mode for matching nodes. Whether to include void nodes in the search. A tuple containing the void node and its path, or undefined if not found. ## Location ### `findPath` Find the path of a Plate node in the editor. The node to find the path for in the editor tree. Options for finding the node's path. Common query options for finding nodes. Whether to ignore non-selectable nodes during traversal. Whether to traverse in reverse order. Whether to ensure the operation works universally across all nodes. Query mode for finding nodes. Whether to include void nodes in the search. The path of the node if found, undefined otherwise. ### `path` Get the path of a location. The location to get the path from. Defaults to current selection. The path of the location. ### `point` Get the `start` or `end` (default is `start`) point of a location. The location to get the point from. Defaults to current selection. Options for getting the point. Which edge of the location to get the point from. The point at the specified location and edge. ### `positions` Iterate through all possible point positions in the document. Where to start iterating. Defaults to editor selection. - `'offset'`: Moves to the next offset Point - `'character'`: Moves to the next character - `'word'`: Moves to the position after the next word - `'line'` | 'block': Moves between block boundaries When true returns positions in reverse order. Whether to include positions inside void nodes. Whether to skip positions in non-selectable nodes. A generator that yields each valid point position in the document. ### `nodesRange` Returns the range spanning the given node entries. The node entries to get the range for. The range spanning the nodes, or undefined if no valid range can be created. ### `range` Create a range between two locations. The location to create the range at. Defaults to current selection. The focus (end) point of the range. The anchor (start) point of the range. A new range between the specified points. ### `start` Get the start point of a location. The location to get the start point from. Options for getting the start point. Get the start point of the next node instead of the current one. The start point of the location. ### `unhangRange` Convert a range into a non-hanging one. A "hanging" range is one created by the browser's "triple-click" selection behavior. When triple-clicking a block, the browser selects from the start of that block to the start of the _next_ block. The range thus "hangs over" into the next block. If `unhangRange` is given such a range, it moves the end backwards until it's in a non-empty text node that precedes the hanging block. Note that `unhangRange` is designed for the specific purpose of fixing triple-clicked blocks, and therefore currently has a number of caveats: - It does not modify the start of the range; only the end. For example, it does not "unhang" a selection that starts at the end of a previous block. - It only does anything if the start block is fully selected. For example, it does not handle ranges created by double-clicking the end of a paragraph (which browsers treat by selecting from the end of that paragraph to the start of the next). The range to unhang. Options for un-hanging the range. Allow placing the end of the selection in a void node. A new range with the end point moved backwards if it was hanging. ## Element ### `elementReadOnly` Check if an element is read-only. The element to check for read-only status. True if the element is read-only, false otherwise. ### `isBlock` Check if a value is a block `Element` object. The value to check. True if the value is a block element, false otherwise. ### `isInline` Check if a value is an inline `Element` object. The element to check. True if the element is inline, false otherwise. ### `isSelectable` Check if a value is a selectable `Element` object. The element to check. True if the element is selectable, false otherwise. ### `isVoid` Check if an element is void. The element to check for void status. True if the element is void, false otherwise. ### `markableVoid` Check if an element is a markable void element. The element to check for markable void status. True if the element is a markable void element, false otherwise. ## Ref ### `pathRef` Create a mutable ref for a `Path`. The path to reference. Options for the path reference. The direction to resolve the ref when ambiguous: - `'forward'`: Resolve to the next valid position - `'backward'`: Resolve to the previous valid position - `null`: Do not resolve to any position A mutable reference that updates its path as operations are applied to the editor. ### `pathRefs` Get the set of currently tracked path refs of the editor. The set of tracked path refs. ### `pointRef` Create a mutable ref for a `Point`. The point to reference. Options for the point reference. The direction to resolve the ref when ambiguous: - `'forward'`: Resolve to the next valid position - `'backward'`: Resolve to the previous valid position - `null`: Do not resolve to any position A mutable reference that updates its point as operations are applied to the editor. ### `pointRefs` Get the set of currently tracked point refs of the editor. The set of tracked point refs. ### `rangeRef` Create a mutable ref for a `Range`. The range to reference. Options for the range reference. The direction to resolve the ref when ambiguous: - `'forward'`: Resolve both points forward - `'backward'`: Resolve both points backward - `'outward'`: Resolve start backward and end forward - `'inward'`: Resolve start forward and end backward - `null`: Do not resolve to any position A mutable reference that updates its range as operations are applied to the editor. ### `rangeRefs` Get the set of currently tracked range refs of the editor. The set of tracked range refs. ## DOM ### `findDocumentOrShadowRoot` Find the document or shadow root from the editor. The document or shadow root containing the editor. ### `findEventRange` Get the target range from a DOM event. The DOM event to get the range from. The range at the event target, or null if no valid range found. ### `findKey` Find a key for a Plate node. Returns an instance of `Key` which looks like `{ id: string }`. The node to find the key for. The key associated with the node. ### `getWindow` Get the window object from the editor. The window object associated with the editor. ### `hasDOMNode` Check if a DOM node is within the editor. The DOM node to check. Options for checking the DOM node. Whether to check if the node is in an editable element. True if the DOM node is within the editor, false otherwise. ### `hasEditableTarget` Check if a DOM target is editable. The DOM target to check. True if the target is editable, false otherwise. ### `hasRange` Check if the editor has a range. The range to check. True if the editor has the specified range, false otherwise. ### `hasSelectableTarget` Check if a DOM target is selectable. The DOM target to check. True if the target is selectable, false otherwise. ### `hasTarget` Check if a DOM target exists. The DOM target to check. True if the target exists, false otherwise. ### `isComposing` Check if the user is currently composing inside the editor. True if the user is currently composing text, false otherwise. ### `isFocused` Check if the editor is focused. True if the editor has focus, false otherwise. ### `isReadOnly` Check if the editor is in read-only mode. True if the editor is read-only, false otherwise. ### `toDOMNode` Find the native DOM element from a Plate node. The Plate node to convert to a DOM element. The corresponding DOM element for the Plate node. ### `toDOMPoint` Find a native DOM selection point from a Plate point. The Plate point to convert to a DOM point. A tuple of [node, offset] representing the DOM point. ### `toDOMRange` Find a native DOM range from a Plate range. The Plate range to convert to a DOM range. The corresponding DOM range for the Plate range. ### `toSlateNode` Find a Plate node from a native DOM element. The DOM node to convert to a Plate node. The corresponding Plate node if found, undefined otherwise. ### `toSlatePoint` Find a Plate point from a DOM selection point. The DOM point to convert to a Plate point. The corresponding Plate point if found, undefined otherwise. ### `toSlateRange` Find a Plate range from a DOM range. The DOM range to convert to a Plate range. The corresponding Plate range if found, undefined otherwise. ## Callback ### `onChange` Called when there is a change in the editor. The operation that triggered the change. ## Core ### `getDirtyPaths` Get the paths that need to be normalized after an operation. The operation that triggered normalization. An array of paths that need to be normalized after the operation. ### `shouldMergeNodes` Decide whether two adjacent node entries should merge. Plate calls this before `editor.tf.mergeNodes()` applies a merge operation. Previous node entry at the merge boundary. Next node entry at the merge boundary. Merge direction metadata. True when the nodes should merge, false when the merge should stop. ### `shouldNormalizeNode` Override this method to prevent normalizing a specific node. Defaults to returning `true`. The node entry (node and path) to check. True if the node should be normalized, false otherwise. ### `setNormalizing` Manually control the editor's normalizing state. Whether the editor should normalize after each operation. ### `shouldNormalize` Controls whether the editor should normalize after an operation. Override this method to prevent normalizing in certain situations. The paths that need to be normalized. The initial number of dirty paths before normalization started. The current normalization iteration count. The operation that triggered the normalization. True if the editor should normalize, false otherwise. ## History ### `isMerging` Get the merge flag's current value. True if the editor is currently merging operations, false otherwise. ### `isSaving` Get the saving flag's current value. True if the editor is currently saving, false otherwise. ### `isSplittingOnce` Get the splitting flag's current value. True if the editor is currently performing a single split operation, false otherwise. ## Utils ### `create.block` Default block factory for creating new block elements. Partial element properties to merge into the new block. Path for the new block. A new block element. ### `create.value` Default value factory for creating new editor values. A new editor value. 4e:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L4f",null,{"files":[{"path":"../../content/docs/api/slate/editor-api.mdx","content":"$50","type":"registry:file","target":"content/docs/plate/api/slate/editor-api.mdx"}],"className":"h-[70svh] min-h-80"}]]}]