ContextQMD
Back to Plate

Editor API

docs/api/slate/editor-api.mdx

1.0.045.5 KB
Original Source

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(). This allows you to reference a location by either:

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.

<API name="QueryMode"> <APIOptions type="QueryMode"> <APIItem name="mode" type="'all' | 'highest' | 'lowest'" optional> - `'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' })
```
</APIItem> </APIOptions> </API>

QueryOptions

Common options for querying nodes in the editor.

<API name="QueryOptions"> <APIOptions type="QueryOptions<V>"> <APIItem name="at" type="At" optional> Where to start querying from. Defaults to current editor selection. </APIItem> <APIItem name="block" type="boolean" optional> Match block nodes. When true, only matches block elements. </APIItem> <APIItem name="empty" type="boolean" optional> Match empty/non-empty nodes. - When true, matches only empty nodes - When false, matches only non-empty nodes </APIItem> <APIItem name="id" type="boolean | string" optional> Match the node by id. - When true, matches all nodes with an id - When string, matches nodes with that specific id </APIItem> <APIItem name="match" type="Predicate<NodeIn<V>>" optional> Custom function or object to match nodes. - Function: `(node, path) => boolean` - Object: Key-value pairs that should match the node </APIItem> <APIItem name="text" type="boolean" optional> Match text nodes. When true, matches only text nodes. </APIItem> </APIOptions> </API>

editor.api

above

Get the matching ancestor above a location in the document.

<API name="above"> <APIOptions type="EditorAboveOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode options. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="NodeEntry<N> | undefined"> A tuple containing the matching ancestor node and its path, or `undefined` if no match is found. </APIReturns> </API>

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
<API name="block"> <APIOptions type="EditorBlockOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching blocks. </APIItem> <APIItem name="at" type="At | Span" optional> The location to query at. Defaults to current selection. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to ignore non-selectable nodes during traversal. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order. </APIItem> <APIItem name="universal" type="boolean" optional> Whether to ensure the operation works universally across all nodes. </APIItem> <APIItem name="above" type="boolean" optional> If true, get the block above the location. Ignored if `at` is not a block path. </APIItem> <APIItem name="highest" type="boolean" optional> If true, get the highest block at the location (root-level block). </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching blocks. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="NodeEntry<N> | undefined"> The matching block node entry or `undefined` if no match is found. </APIReturns> </API>

blocks

Returns all matching blocks.

<API name="blocks"> <APIOptions type="EditorNodesOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching blocks. </APIItem> <APIItem name="at" type="At | Span" optional> The location to query at. Defaults to current selection. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to ignore non-selectable nodes during traversal. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order. </APIItem> <APIItem name="universal" type="boolean" optional> Whether to ensure the operation works universally across all nodes. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching blocks. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="NodeEntry<ElementIn<V>>[]"> An array of matching block node entries. </APIReturns> </API>

edgeBlocks

Returns the edge blocks above a location (default: selection).
Useful for retrieving the start and end block of a range.

<API name="edgeBlocks"> <APIOptions type="EditorNodesOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching blocks. </APIItem> <APIItem name="at" type="At | Span" optional> The location to get edge blocks from. Defaults to current selection. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to ignore non-selectable nodes during traversal. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order. </APIItem> <APIItem name="universal" type="boolean" optional> Whether to ensure the operation works universally across all nodes. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching blocks. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="[NodeEntry<N1>, NodeEntry<N2>] | null"> A tuple of `[startBlock, endBlock]` above the location, or `null` if not found. </APIReturns> </API>

first

Get the first node at a location.

<API name="first"> <APIParameters> <APIItem name="at" type="At"> The location to get the first node from. </APIItem> </APIParameters> <APIReturns type="NodeEntry<DescendantIn<V>> | undefined"> A tuple containing the first node and its path, or undefined if not found. </APIReturns> </API>

fragment

Get the fragment at a location or selection.

<API name="fragment"> <APIParameters> <APIItem name="at" type="At | null" optional> The location to extract the fragment from. Defaults to current selection. </APIItem> <APIItem name="options" type="EditorFragmentOptions" optional> Options for extracting and processing the fragment. </APIItem> </APIParameters> <APIReturns type="ElementOrTextIn<V>[] | undefined"> The fragment at the location. </APIReturns> </API>

getFragment

Returns the fragment at the current selection. Used when cutting or copying, as an example, to get the fragment at the current selection.

<API name="getFragment"> <APIParameters> <APIItem name="at" type="At" optional> The location to get the fragment from. Defaults to current selection. </APIItem> </APIParameters> <APIReturns type="ElementOrTextIn<V>[]"> The fragment at the current selection. </APIReturns> </API>

hasBlocks

Check if a node has block children.

<API name="hasBlocks"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element has block children, false otherwise. </APIReturns> </API>

hasInlines

Check if a node has inline and text children.

<API name="hasInlines"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element has inline and text children, false otherwise. </APIReturns> </API>

hasMark

Check if mark is active at selection.

<API name="hasMark"> <APIParameters> <APIItem name="key" type="keyof MarksIn<V>"> The mark key to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the mark is active at the current selection, false otherwise. </APIReturns> </API>

hasPath

Check if a path exists in the editor.

<API name="hasPath"> <APIParameters> <APIItem name="path" type="Path"> The path to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the path exists, false otherwise. </APIReturns> </API>

hasTexts

Check if a node has text children.

<API name="hasTexts"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element has text children, false otherwise. </APIReturns> </API>

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
<API name="isAt"> <APIOptions type="object"> <APIItem name="at" type="At" optional> The location to check. Defaults to current selection. </APIItem> <APIItem name="text" type="boolean" optional> Check if range is in a single text node. </APIItem> <APIItem name="block" type="boolean" optional> Check if range is in a single block. </APIItem> <APIItem name="blocks" type="boolean" optional> Check if range is across multiple blocks. </APIItem> <APIItem name="start" type="boolean" optional> Check if at start position. </APIItem> <APIItem name="end" type="boolean" optional> Check if at end position. </APIItem> <APIItem name="word" type="boolean" optional> Check relative to word boundaries. </APIItem> </APIOptions> <APIReturns type="boolean"> True if the location matches all specified position criteria, false otherwise. </APIReturns> </API>

isCollapsed

Check if the selection is collapsed (start and end points are the same).

<API name="isCollapsed"> <APIReturns type="boolean"> True if the selection is collapsed, false otherwise. </APIReturns> </API>

isEdge

Check if a point is an edge of a location.

<API name="isEdge"> <APIParameters> <APIItem name="point" type="Point"> The point to check. </APIItem> <APIItem name="at" type="At" optional> The location to check against. Defaults to current selection. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the point is an edge of the location, false otherwise. </APIReturns> </API>

isEditorEnd

Check if selection is at editor end.

<API name="isEditorEnd"> <APIReturns type="boolean"> True if the selection is at the editor end, false otherwise. </APIReturns> </API>

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
<API name="isEmpty"> <APIParameters> <APIItem name="at" type="At | null" optional> The location to check for emptiness. Defaults to current selection. </APIItem> <APIItem name="options" type="EditorEmptyOptions" optional> Options for determining emptiness. </APIItem> </APIParameters> <APIOptions type="EditorEmptyOptions"> <APIItem name="...options" type="QueryOptions<V>" optional /> <APIItem name="after" type="boolean" optional> Check if text after selection is empty. </APIItem> <APIItem name="block" type="boolean" optional> Check if the block above location is empty. </APIItem> </APIOptions> <APIReturns type="boolean" /> </API>

isEnd

Check if a point is the end point of a location.

<API name="isEnd"> <APIParameters> <APIItem name="point" type="Point"> The point to check. </APIItem> <APIItem name="at" type="At" optional> The location to check against. Defaults to current selection. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the point is the end point of the location, false otherwise. </APIReturns> </API>

isExpanded

Check if the selection is expanded (start and end points are different).

<API name="isExpanded"> <APIReturns type="boolean"> True if the selection is expanded, false otherwise. </APIReturns> </API>

isNormalizing

Check if the editor is currently normalizing after each operation.

<API name="isNormalizing"> <APIReturns type="boolean"> True if the editor is currently normalizing, false otherwise. </APIReturns> </API>

isStart

Check if a point is the start point of a location.

<API name="isStart"> <APIParameters> <APIItem name="point" type="Point"> The point to check. </APIItem> <APIItem name="at" type="At" optional> The location to check against. Defaults to current selection. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the point is the start point of the location, false otherwise. </APIReturns> </API>

isSelected

Check if a path is selected by the current selection.

<API name="isSelected"> <APIParameters> <APIItem name="target" type="Path | TRange"> The path or range to check. </APIItem> <APIItem name="options" type="EditorIsSelectedOptions" optional> Options for checking selection. </APIItem> </APIParameters> <APIOptions type="EditorIsSelectedOptions"> <APIItem name="contains" type="boolean" optional> Check if selection contains the entire path range. </APIItem> </APIOptions> <APIReturns type="boolean"> True if the path is selected, false otherwise. </APIReturns> </API>

leaf

Get the leaf text node at a location.

<API name="leaf"> <APIParameters> <APIItem name="at" type="At"> The location to get the leaf from. </APIItem> <APIItem name="options" type="EditorLeafOptions" optional> Options for getting the leaf. </APIItem> </APIParameters> <APIOptions type="EditorLeafOptions"> <APIItem name="depth" type="number" optional> The depth to traverse to find the leaf. </APIItem> <APIItem name="edge" type="LeafEdge" optional> Which edge of the location to get the leaf from (`'start' | 'end'`). </APIItem> </APIOptions> <APIReturns type="NodeEntry<TextIn<V>> | undefined"> A tuple containing the leaf text node and its path, or undefined if not found. </APIReturns> </API>

levels

Iterate through all levels at a location. This includes all ancestors up to the root editor node.

<API name="levels"> <APIOptions type="EditorLevelsOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching levels. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order (bottom-up vs. top-down). </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the traversal. </APIItem> </APIOptions> <APIReturns type="Generator<NodeEntry<NodeIn<V>>, void, undefined>"> A generator that yields tuples of [node, path] for each ancestor level. </APIReturns> </API>

last

Get the last node at a location.

<API name="last"> <APIParameters> <APIItem name="at" type="At"> The location to get the last node from. </APIItem> <APIItem name="options" type="EditorLastOptions" optional> Options for getting the last node. </APIItem> </APIParameters> <APIOptions type="EditorLastOptions"> <APIItem name="level" type="number" optional> Get last node at this level (0-based). </APIItem> </APIOptions> <APIReturns type="NodeEntry<DescendantIn<V>> | undefined"> A tuple containing the last node and its path, or undefined if not found. </APIReturns> </API>

mark

Returns the selection mark value by key.

<API name="mark"> <APIParameters> <APIItem name="key" type="keyof MarksIn<V>"> The mark key. </APIItem> </APIParameters> <APIReturns type="MarksIn<V>[K] | null | undefined"> The mark value if it exists, null if not set, or undefined if multiple different values exist. </APIReturns> </API>

marks

Get the marks that would be added to text at the current selection.

<API name="marks"> <APIReturns type="MarksIn<V> | null"> The marks at the current selection, or null if there are no marks. </APIReturns> </API>

next

Get the matching node in the branch of the document after a location.

<API name="next"> <APIOptions type="EditorNextOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching nodes. </APIItem> <APIItem name="at" type="At | Span" optional> The location to start searching from. Defaults to current selection. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching nodes. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> <APIItem name="from" type="'after' | 'child'" optional> - `'after'`: Start from point after current location - `'child'`: Start from the first child of current path </APIItem> </APIOptions> <APIReturns type="NodeEntry<DescendantIn<V>> | undefined"> A tuple containing the next matching node and its path, or undefined if not found. </APIReturns> </API>

node

Get the node at a location or find the first node that matches options.

<API name="node"> <APIParameters> <APIItem name="at" type="At" optional> The location to get a node from. </APIItem> <APIItem name="nodeOptions" type="EditorNodeOptions" optional> Options for getting a node. </APIItem> </APIParameters> <APIOptions type="EditorNodeOptions"> <APIItem name="depth" type="number" optional> The depth to traverse to find the node. </APIItem> <APIItem name="edge" type="'start' | 'end'" optional> Which edge of the location to get the node from. </APIItem> </APIOptions> <APIReturns type="NodeEntry<NodeIn<V>> | undefined"> A tuple containing the matching node and its path, or undefined if not found. </APIReturns> </API>

nodes

Iterate through all nodes in the editor that match the given options.

<API name="nodes"> <APIOptions type="EditorNodesOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching nodes. </APIItem> <APIItem name="at" type="At | Span" optional> Where to start iterating. Defaults to editor selection. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to ignore non-selectable nodes during traversal. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order. </APIItem> <APIItem name="universal" type="boolean" optional> Whether to ensure the operation works universally across all nodes. </APIItem> <APIItem name="mode" type="QueryMode" optional> - `'all'`: Return all matching nodes - `'highest'`: Return highest-level matching nodes - `'lowest'`: Return lowest-level matching nodes </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="Generator<NodeEntry<DescendantIn<V>>, void, undefined>"> A generator that yields tuples of [node, path] for each matching node. </APIReturns> </API>

parent

Get the parent node of a location.

<API name="parent"> <APIParameters> <APIItem name="at" type="At" optional> The location to get the parent from. </APIItem> <APIItem name="options" type="EditorParentOptions" optional> Options for getting the parent node. </APIItem> </APIParameters> <APIOptions type="EditorParentOptions"> <APIItem name="depth" type="number" optional> Number of levels to traverse up to find the parent. </APIItem> <APIItem name="edge" type="'start' | 'end'" optional> Which edge of the location to get the parent from. </APIItem> </APIOptions> <APIReturns type="NodeEntry<AncestorIn<V>> | undefined"> A tuple containing the parent node and its path, or undefined if not found. </APIReturns> </API>

previous

Get the matching node in the branch of the document before a location.

<API name="previous"> <APIOptions type="EditorPreviousOptions<V>"> <APIItem name="...options" type="QueryOptions<V>" optional> Common query options for matching nodes. </APIItem> <APIItem name="at" type="At | Span" optional> The location to start searching from. Defaults to current selection. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching nodes. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> <APIItem name="sibling" type="boolean" optional> Whether to get the previous sibling node instead of any previous node. </APIItem> <APIItem name="from" type="'before' | 'parent'" optional> - `'before'`: Start from point before current location - `'parent'`: Start from parent of current location </APIItem> </APIOptions> <APIReturns type="NodeEntry<DescendantIn<V>> | undefined"> A tuple containing the previous matching node and its path, or undefined if not found. </APIReturns> </API>

prop

Get a property value from a list of nodes. Returns undefined if the property value is not consistent across all nodes.

<API name="prop"> <APIOptions type="EditorPropOptions<V>"> <APIItem name="nodes" type="TElement[]"> The list of nodes to get the property value from. </APIItem> <APIItem name="key" type="string" optional> The property key to get from the nodes. </APIItem> <APIItem name="defaultValue" type="string" optional> Default value to return if property is not found. </APIItem> <APIItem name="getProp" type="(node: DescendantIn<V>) => any" optional> Custom function to extract property value from a node. </APIItem> <APIItem name="mode" type="'all' | 'block' | 'text'" optional> - `'all'`: Get property from all nodes - `'block'`: Get property from the first block node - `'text'`: Get property from the first text node </APIItem> </APIOptions> <APIReturns type="string | undefined"> The consistent property value across all nodes, or `undefined` if values differ. </APIReturns> </API>

string

Get the text string content of a location.

<API name="string"> <APIParameters> <APIItem name="at" type="At" optional> The location to get text content from. Defaults to current selection. </APIItem> <APIItem name="options" type="EditorStringOptions" optional> Options for getting text content. </APIItem> </APIParameters> <APIOptions type="EditorStringOptions"> <APIItem name="voids" type="boolean" optional> Whether to include text content from void nodes. </APIItem> </APIOptions> <APIReturns type="string"> The text content at the specified location. </APIReturns> </API>

void

Match a void node in the current branch of the editor.

<API name="void"> <APIOptions type="EditorVoidOptions"> <APIItem name="at" type="At" optional> The location to search from. Defaults to current selection. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for matching nodes. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="NodeEntry<ElementIn<V>> | undefined"> A tuple containing the void node and its path, or undefined if not found. </APIReturns> </API>

Location

findPath

Find the path of a Plate node in the editor.

<API name="findPath"> <APIParameters> <APIItem name="node" type="TNode"> The node to find the path for in the editor tree. </APIItem> <APIItem name="options" type="EditorFindPathOptions" optional> Options for finding the node's path. </APIItem> </APIParameters> <APIOptions type="EditorFindPathOptions"> <APIItem name="...options" type="QueryOptions<Value>" optional> Common query options for finding nodes. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to ignore non-selectable nodes during traversal. </APIItem> <APIItem name="reverse" type="boolean" optional> Whether to traverse in reverse order. </APIItem> <APIItem name="universal" type="boolean" optional> Whether to ensure the operation works universally across all nodes. </APIItem> <APIItem name="mode" type="QueryMode" optional> Query mode for finding nodes. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include void nodes in the search. </APIItem> </APIOptions> <APIReturns type="Path | undefined"> The path of the node if found, undefined otherwise. </APIReturns> </API>

path

Get the path of a location.

<API name="path"> <APIParameters> <APIItem name="at" type="At" optional> The location to get the path from. Defaults to current selection. </APIItem> </APIParameters> <APIReturns type="Path"> The path of the location. </APIReturns> </API>

point

Get the start or end (default is start) point of a location.

<API name="point"> <APIParameters> <APIItem name="at" type="At" optional> The location to get the point from. Defaults to current selection. </APIItem> <APIItem name="options" type="EditorPointOptions" optional> Options for getting the point. </APIItem> </APIParameters> <APIOptions type="EditorPointOptions"> <APIItem name="edge" type="'start' | 'end'" optional> Which edge of the location to get the point from. </APIItem> </APIOptions> <APIReturns type="Point"> The point at the specified location and edge. </APIReturns> </API>

positions

Iterate through all possible point positions in the document.

<API name="positions"> <APIOptions type="EditorPositionsOptions"> <APIItem name="at" type="At" optional> Where to start iterating. Defaults to editor selection. </APIItem> <APIItem name="unit" type="TextUnitAdjustment" optional> - `'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 </APIItem> <APIItem name="reverse" type="boolean" optional> When true returns positions in reverse order. </APIItem> <APIItem name="voids" type="boolean" optional> Whether to include positions inside void nodes. </APIItem> <APIItem name="ignoreNonSelectable" type="boolean" optional> Whether to skip positions in non-selectable nodes. </APIItem> </APIOptions> <APIReturns type="Generator<Point, void, undefined>"> A generator that yields each valid point position in the document. </APIReturns> </API>

nodesRange

Returns the range spanning the given node entries.

<API name="nodesRange"> <APIParameters> <APIItem name="nodes" type="NodeEntry[]"> The node entries to get the range for. </APIItem> </APIParameters> <APIReturns type="TRange | undefined"> The range spanning the nodes, or undefined if no valid range can be created. </APIReturns> </API>

range

Create a range between two locations.

<API name="range"> <APIOptions type="EditorRangeOptions"> <APIItem name="at" type="At" optional> The location to create the range at. Defaults to current selection. </APIItem> <APIItem name="focus" type="Point" optional> The focus (end) point of the range. </APIItem> <APIItem name="anchor" type="Point" optional> The anchor (start) point of the range. </APIItem> </APIOptions> <APIReturns type="TRange"> A new range between the specified points. </APIReturns> </API>

start

Get the start point of a location.

<API name="start"> <APIParameters> <APIItem name="at" type="At" optional> The location to get the start point from. </APIItem> <APIItem name="options" type="EditorStartOptions" optional> Options for getting the start point. </APIItem> </APIParameters> <APIOptions type="EditorStartOptions"> <APIItem name="next" type="boolean" optional> Get the start point of the next node instead of the current one. </APIItem> </APIOptions> <APIReturns type="Point"> The start point of the location. </APIReturns> </API>

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).
<API name="unhangRange"> <APIParameters> <APIItem name="range" type="TRange"> The range to unhang. </APIItem> <APIItem name="options" type="EditorUnhangRangeOptions" optional> Options for un-hanging the range. </APIItem> </APIParameters> <APIOptions type="EditorUnhangRangeOptions"> <APIItem name="voids" type="boolean" optional> Allow placing the end of the selection in a void node. </APIItem> </APIOptions> <APIReturns type="TRange"> A new range with the end point moved backwards if it was hanging. </APIReturns> </API>

Element

elementReadOnly

Check if an element is read-only.

<API name="elementReadOnly"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check for read-only status. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element is read-only, false otherwise. </APIReturns> </API>

isBlock

Check if a value is a block Element object.

<API name="isBlock"> <APIParameters> <APIItem name="value" type="any"> The value to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the value is a block element, false otherwise. </APIReturns> </API>

isInline

Check if a value is an inline Element object.

<API name="isInline"> <APIParameters> <APIItem name="element" type="DescendantIn<V>"> The element to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element is inline, false otherwise. </APIReturns> </API>

isSelectable

Check if a value is a selectable Element object.

<API name="isSelectable"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element is selectable, false otherwise. </APIReturns> </API>

isVoid

Check if an element is void.

<API name="isVoid"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check for void status. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element is void, false otherwise. </APIReturns> </API>

markableVoid

Check if an element is a markable void element.

<API name="markableVoid"> <APIParameters> <APIItem name="element" type="ElementIn<V>"> The element to check for markable void status. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the element is a markable void element, false otherwise. </APIReturns> </API>

Ref

pathRef

Create a mutable ref for a Path.

<API name="pathRef"> <APIParameters> <APIItem name="path" type="Path"> The path to reference. </APIItem> <APIItem name="options" type="EditorPathRefOptions" optional> Options for the path reference. </APIItem> </APIParameters> <APIOptions type="EditorPathRefOptions"> <APIItem name="affinity" type="TextDirection | null" optional> 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 </APIItem> </APIOptions> <APIReturns type="PathRef"> A mutable reference that updates its path as operations are applied to the editor. </APIReturns> </API>

pathRefs

Get the set of currently tracked path refs of the editor.

<API name="pathRefs"> <APIReturns type="Set<PathRef>"> The set of tracked path refs. </APIReturns> </API>

pointRef

Create a mutable ref for a Point.

<API name="pointRef"> <APIParameters> <APIItem name="point" type="Point"> The point to reference. </APIItem> <APIItem name="options" type="EditorPointRefOptions" optional> Options for the point reference. </APIItem> </APIParameters> <APIOptions type="EditorPointRefOptions"> <APIItem name="affinity" type="TextDirection | null" optional> 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 </APIItem> </APIOptions> <APIReturns type="PointRef"> A mutable reference that updates its point as operations are applied to the editor. </APIReturns> </API>

pointRefs

Get the set of currently tracked point refs of the editor.

<API name="pointRefs"> <APIReturns type="Set<PointRef>"> The set of tracked point refs. </APIReturns> </API>

rangeRef

Create a mutable ref for a Range.

<API name="rangeRef"> <APIParameters> <APIItem name="range" type="TRange"> The range to reference. </APIItem> <APIItem name="options" type="EditorRangeRefOptions" optional> Options for the range reference. </APIItem> </APIParameters> <APIOptions type="EditorRangeRefOptions"> <APIItem name="affinity" type="RangeDirection | null" optional> 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 </APIItem> </APIOptions> <APIReturns type="RangeRef"> A mutable reference that updates its range as operations are applied to the editor. </APIReturns> </API>

rangeRefs

Get the set of currently tracked range refs of the editor.

<API name="rangeRefs"> <APIReturns type="Set<RangeRef>"> The set of tracked range refs. </APIReturns> </API>

DOM

findDocumentOrShadowRoot

Find the document or shadow root from the editor.

<API name="findDocumentOrShadowRoot"> <APIReturns type="Document | ShadowRoot"> The document or shadow root containing the editor. </APIReturns> </API>

findEventRange

Get the target range from a DOM event.

<API name="findEventRange"> <APIParameters> <APIItem name="event" type="Event"> The DOM event to get the range from. </APIItem> </APIParameters> <APIReturns type="TRange | null"> The range at the event target, or null if no valid range found. </APIReturns> </API>

findKey

Find a key for a Plate node. Returns an instance of Key which looks like { id: string }.

<API name="findKey"> <APIParameters> <APIItem name="node" type="TNode"> The node to find the key for. </APIItem> </APIParameters> <APIReturns type="Key"> The key associated with the node. </APIReturns> </API>

getWindow

Get the window object from the editor.

<API name="getWindow"> <APIReturns type="Window"> The window object associated with the editor. </APIReturns> </API>

hasDOMNode

Check if a DOM node is within the editor.

<API name="hasDOMNode"> <APIParameters> <APIItem name="target" type="Node"> The DOM node to check. </APIItem> <APIItem name="options" type="object" optional> Options for checking the DOM node. </APIItem> </APIParameters> <APIOptions type="object"> <APIItem name="editable" type="boolean" optional> Whether to check if the node is in an editable element. </APIItem> </APIOptions> <APIReturns type="boolean"> True if the DOM node is within the editor, false otherwise. </APIReturns> </API>

hasEditableTarget

Check if a DOM target is editable.

<API name="hasEditableTarget"> <APIParameters> <APIItem name="target" type="EventTarget | null"> The DOM target to check. </APIItem> </APIParameters> <APIReturns type="target is Node"> True if the target is editable, false otherwise. </APIReturns> </API>

hasRange

Check if the editor has a range.

<API name="hasRange"> <APIParameters> <APIItem name="range" type="TRange"> The range to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the editor has the specified range, false otherwise. </APIReturns> </API>

hasSelectableTarget

Check if a DOM target is selectable.

<API name="hasSelectableTarget"> <APIParameters> <APIItem name="target" type="EventTarget | null"> The DOM target to check. </APIItem> </APIParameters> <APIReturns type="target is Node"> True if the target is selectable, false otherwise. </APIReturns> </API>

hasTarget

Check if a DOM target exists.

<API name="hasTarget"> <APIParameters> <APIItem name="target" type="EventTarget | null"> The DOM target to check. </APIItem> </APIParameters> <APIReturns type="target is Node"> True if the target exists, false otherwise. </APIReturns> </API>

isComposing

Check if the user is currently composing inside the editor.

<API name="isComposing"> <APIReturns type="boolean"> True if the user is currently composing text, false otherwise. </APIReturns> </API>

isFocused

Check if the editor is focused.

<API name="isFocused"> <APIReturns type="boolean"> True if the editor has focus, false otherwise. </APIReturns> </API>

isReadOnly

Check if the editor is in read-only mode.

<API name="isReadOnly"> <APIReturns type="boolean"> True if the editor is read-only, false otherwise. </APIReturns> </API>

toDOMNode

Find the native DOM element from a Plate node.

<API name="toDOMNode"> <APIOptions type="TNode"> <APIItem name="node" type="TNode"> The Plate node to convert to a DOM element. </APIItem> </APIOptions> <APIReturns type="HTMLElement"> The corresponding DOM element for the Plate node. </APIReturns> </API>

toDOMPoint

Find a native DOM selection point from a Plate point.

<API name="toDOMPoint"> <APIOptions type="Point"> <APIItem name="point" type="Point"> The Plate point to convert to a DOM point. </APIItem> </APIOptions> <APIReturns type="DOMPoint"> A tuple of [node, offset] representing the DOM point. </APIReturns> </API>

toDOMRange

Find a native DOM range from a Plate range.

<API name="toDOMRange"> <APIOptions type="TRange"> <APIItem name="range" type="TRange"> The Plate range to convert to a DOM range. </APIItem> </APIOptions> <APIReturns type="DOMRange"> The corresponding DOM range for the Plate range. </APIReturns> </API>

toSlateNode

Find a Plate node from a native DOM element.

<API name="toSlateNode"> <APIOptions type="DOMNode"> <APIItem name="domNode" type="DOMNode"> The DOM node to convert to a Plate node. </APIItem> </APIOptions> <APIReturns type="TNode | undefined"> The corresponding Plate node if found, undefined otherwise. </APIReturns> </API>

toSlatePoint

Find a Plate point from a DOM selection point.

<API name="toSlatePoint"> <APIOptions type="DOMPoint"> <APIItem name="domPoint" type="DOMPoint"> The DOM point to convert to a Plate point. </APIItem> </APIOptions> <APIReturns type="Point | undefined"> The corresponding Plate point if found, undefined otherwise. </APIReturns> </API>

toSlateRange

Find a Plate range from a DOM range.

<API name="toSlateRange"> <APIOptions type="DOMRange"> <APIItem name="domRange" type="DOMRange"> The DOM range to convert to a Plate range. </APIItem> </APIOptions> <APIReturns type="TRange | undefined"> The corresponding Plate range if found, undefined otherwise. </APIReturns> </API>

Callback

onChange

Called when there is a change in the editor.

<API name="onChange"> <APIOptions type="object"> <APIItem name="operation" type="Operation" optional> The operation that triggered the change. </APIItem> </APIOptions> </API>

Core

getDirtyPaths

Get the paths that need to be normalized after an operation.

<API name="getDirtyPaths"> <APIParameters> <APIItem name="operation" type="Operation<N extends DescendantIn<V>>"> The operation that triggered normalization. </APIItem> </APIParameters> <APIReturns type="Path[]"> An array of paths that need to be normalized after the operation. </APIReturns> </API>

shouldNormalizeNode

Override this method to prevent normalizing a specific node. Defaults to returning true.

<API name="shouldNormalizeNode"> <APIParameters> <APIItem name="entry" type="NodeEntry"> The node entry (node and path) to check. </APIItem> </APIParameters> <APIReturns type="boolean"> True if the node should be normalized, false otherwise. </APIReturns> </API>

setNormalizing

Manually control the editor's normalizing state.

<API name="setNormalizing"> <APIOptions type="boolean"> <APIItem name="isNormalizing" type="boolean"> Whether the editor should normalize after each operation. </APIItem> </APIOptions> </API>

shouldNormalize

Controls whether the editor should normalize after an operation. Override this method to prevent normalizing in certain situations.

<API name="shouldNormalize"> <APIOptions type="object"> <APIItem name="dirtyPaths" type="Path[]"> The paths that need to be normalized. </APIItem> <APIItem name="initialDirtyPathsLength" type="number"> The initial number of dirty paths before normalization started. </APIItem> <APIItem name="iteration" type="number"> The current normalization iteration count. </APIItem> <APIItem name="operation" type="Operation" optional> The operation that triggered the normalization. </APIItem> </APIOptions> <APIReturns type="boolean"> True if the editor should normalize, false otherwise. </APIReturns> </API>

History

isMerging

Get the merge flag's current value.

<API name="isMerging"> <APIReturns type="boolean"> True if the editor is currently merging operations, false otherwise. </APIReturns> </API>

isSaving

Get the saving flag's current value.

<API name="isSaving"> <APIReturns type="boolean"> True if the editor is currently saving, false otherwise. </APIReturns> </API>

isSplittingOnce

Get the splitting flag's current value.

<API name="isSplittingOnce"> <APIReturns type="boolean"> True if the editor is currently performing a single split operation, false otherwise. </APIReturns> </API>

Utils

create.block

Default block factory for creating new block elements.

<API name="create.block"> <APIParameters> <APIItem name="node" type="Partial<TElement>" optional> Partial element properties to merge into the new block. </APIItem> <APIItem name="path" type="Path" optional> Path for the new block. </APIItem> </APIParameters> <APIReturns type="TElement"> A new block element. </APIReturns> </API>

create.value

Default value factory for creating new editor values.

<API name="create.value"> <APIReturns type="Value"> A new editor value. </APIReturns> </API>