Editor API

API reference for the Editor API.

The Editor API provides a set of helper functions for querying and manipulating the editor state.

editor.api

above

Get the matching ancestor above a location in the document.

Parameters

Collapse all

Returns

    Returns a NodeEntry<N extends AncestorIn<V>> 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.

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

Parameters

Collapse all

Returns

    Returns the matching block node entry or undefined if no match is found.

blocks

Returns all matching blocks.

Parameters

Collapse all

Returns

    Returns an array of NodeEntry<ElementIn<V>> tuples containing the matching block nodes and their paths.

descendant

Returns the first matching descendant.

Parameters

Collapse all

Returns

    Returns a NodeEntry<DescendantIn<V>> tuple containing the first matching descendant node and its path, or undefined if no match is found.

edgeBlocks

Returns the edge blocks above a location (default: selection).

Parameters

Collapse all

Returns

    Returns a tuple of [NodeEntry<ElementIn<V>>, NodeEntry<ElementIn<V>>] containing the start and end block nodes and their paths, or null if not found.

fragment

Get the fragment at a location or selection.

Parameters

Collapse all

    The location to get the fragment from. Defaults to current selection.

Returns

    Returns an array of ElementOrTextIn<V> nodes representing the fragment.

isEmpty

Check if an element is empty, accounting for void nodes.

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

Parameters

Collapse all

Returns

    Returns true if empty, false otherwise.

isAt

Check if a location (point/range) is at a specific position.

// For ranges:
editor.api.isAt({ text: true }) // Check if range is in single text node
editor.api.isAt({ block: true }) // Check if range is in 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

Parameters

Collapse all

Returns

    Returns true if the location matches the specified position criteria.

mark

Returns the selection mark value by key.

Parameters

Collapse all

    The mark key to get the value for.

Returns

    Returns MarksIn<V>[K] | null | undefined - The mark value if it exists, null if the mark is not set, or undefined if there are multiple different values.

nodes

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

Parameters

Collapse all

Returns

    Returns a generator of NodeEntry<DescendantIn<V>> tuples containing the matching nodes and their paths.

prop

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

Parameters

Collapse all

Returns

    Returns string | undefined - The consistent property value if found, or undefined if the property is not consistent across nodes.

DOM

findPath

Find the path of a Slate node.

Parameters

Collapse all

    The node to find the path for.

Returns

    Returns Path | undefined - The path of the node if found, or undefined if not found.

toDOMNode

Find the native DOM element from a Slate node.

Parameters

Collapse all

    The Slate node to find the corresponding DOM element for.

Returns

    Returns HTMLElement - The corresponding DOM element for the Slate node.

toSlateNode

Find a Slate node from a native DOM element.

Parameters

Collapse all

    The DOM node to find the corresponding Slate node for.

Returns

    Returns TNode | undefined - The corresponding Slate node if found, or undefined if not found.

Utils

createPathRef

Create a mutable ref for a Path object.

Parameters

Collapse all

    The path to create a reference for.

Returns

    Returns PathRef - A mutable reference that updates its path as operations are applied to the editor.

createPointRef

Create a mutable ref for a Point object.

Parameters

Collapse all

    The point to create a reference for.

Returns

    Returns PointRef - A mutable reference that updates its point as operations are applied to the editor.

createRangeRef

Create a mutable ref for a Range object.

Parameters

Collapse all

    The range to create a reference for.

Returns

    Returns RangeRef - A mutable reference that updates its range as operations are applied to the editor.

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.

Parameters

Collapse all

    The range to unhang.

Returns

    Returns Range - A new range with the end point moved backwards if it was hanging.

Editor State

shouldMergeNodesRemovePrevNode

Determines whether to remove the previous node when merging nodes.

Parameters

Collapse all

    A tuple containing the previous node and its path.

    A tuple containing the current node and its path.

Returns

    Returns boolean - true if the previous node should be removed during merge, false otherwise.

shouldNormalize

Controls whether the editor should normalize after an operation.

Parameters

Collapse all

Returns

    Returns boolean - true if the editor should normalize, false otherwise.

getDirtyPaths

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

Parameters

Collapse all

    The operation that triggered the normalization.

Returns

    Returns Path[] - An array of paths that need to be normalized after applying the operation.

setNormalizing

Manually control the editor's normalizing state.

Parameters

Collapse all

    Whether the editor should normalize after each operation.

Returns

    Returns void

// Note: Using this incorrectly can leave the editor in an invalid state.

onChange

Called when there is a change in the editor.

Parameters

Collapse all

Returns

    Returns void

Node Operations

last

Get the last node at a location.

Parameters

Collapse all

    The location to get the last node from.

Returns

    Returns NodeEntry<DescendantIn<V>> tuple containing the last node and its path, or undefined if not found.

leaf

Get the leaf text node at a location.

Parameters

Collapse all

    The location to get the leaf from.

Returns

    Returns NodeEntry<TextIn<V>> tuple containing the leaf text node and its path, or undefined if not found.

levels

Iterate through all levels at a location.

Parameters

Collapse all

Returns

    Returns a generator of NodeEntry<NodeIn<V>> tuples containing each ancestor node and its path.

Element Operations

isElementReadOnly

Check if an element is read-only.

Parameters

Collapse all

    The element to check for read-only status.

Returns

    Returns boolean - true if the element is read-only, false otherwise.

isVoid

Check if an element is void.

Parameters

Collapse all

    The element to check.

Returns

    Returns boolean - true if the element is void, false otherwise.

markableVoid

Check if an element is a markable void element.

Parameters

Collapse all

    The element to check for markable void status.

Returns

    Returns boolean - true if the element is a markable void, false otherwise.

Position Operations

positions

Iterate through all possible point positions in the document.

Parameters

Collapse all

Returns

    Returns a generator of Point objects representing each possible position in the document.

Range Operations

range

Create a range between two locations.

Parameters

Collapse all

Returns

    Returns Range - A new range between the specified points.

start

Get the start point of a location.

Parameters

Collapse all

    The location to get the start point from. Defaults to current selection.

Returns

    Returns Point - The start point of the location.

string

Get the text string content of a location.

Parameters

Collapse all

    The location to get text from. Defaults to current selection.

Returns

    Returns string - The text content at the specified location.

next

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

Parameters

Collapse all

Returns

    Returns NodeEntry<DescendantIn<V>> 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.

Parameters

Collapse all

    The location to get the node from. Defaults to current selection.

Returns

    Returns NodeEntry<NodeIn<V>> tuple containing the node and its path, or undefined if not found.

parent

Get the parent node of a location.

Parameters

Collapse all

    The location to get the parent from. Defaults to current selection.

Returns

    Returns NodeEntry<AncestorIn<V>> tuple containing the parent node and its path, or undefined if not found.

path

Get the path of a location.

Parameters

Collapse all

    The location to get the path from. Defaults to current selection.

Returns

    Returns Path - The path at the specified location.

point

Get the start or end point of a location.

Parameters

Collapse all

    The location to get the point from. Defaults to current selection.

Returns

    Returns Point - The point at the specified edge of the location.

previous

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

Parameters

Collapse all

Returns

    Returns NodeEntry<DescendantIn<V>> tuple containing the previous matching node and its path, or undefined if not found.

Reference Operations

createPathRef

Create a mutable ref for a Path object.

Parameters

Collapse all

    The path to create a reference for.

Returns

    Returns PathRef - A mutable reference that updates its path as operations are applied to the editor.

createPointRef

Create a mutable ref for a Point object.

Parameters

Collapse all

    The point to create a reference for.

Returns

    Returns PointRef - A mutable reference that updates its point as operations are applied to the editor.

createRangeRef

Create a mutable ref for a Range object.

Parameters

Collapse all

    The range to create a reference for.

Returns

    Returns RangeRef - A mutable reference that updates its range as operations are applied to the editor.

DOM Operations

findPath

Find the path of a DOM node.

Parameters

Collapse all

    The DOM node to find the path for.

toDOMNode

Find the DOM node from a Slate node.

Parameters

Collapse all

    The Slate node to find the corresponding DOM element for.

Returns

    Returns HTMLElement - The corresponding DOM element for the Slate node.

toDOMPoint

Find a Slate point from a DOM point.

Parameters

Collapse all

    The DOM point to convert to a Slate point.

Returns

    Returns Point | undefined - The corresponding Slate point if found, or undefined if not found.

toDOMRange

Find a DOM range from a Slate range.

Parameters

Collapse all

    The Slate range to convert to a DOM range.

Returns

    Returns DOMRange - The corresponding DOM range for the Slate range.

toSlateNode

Find a Slate node from a native DOM element.

Parameters

Collapse all

    The DOM node to find the corresponding Slate node for.

Returns

    Returns TNode | undefined - The corresponding Slate node if found, or undefined if not found.

toSlatePoint

Find a Slate point from a DOM point.

Parameters

Collapse all

    The DOM point to convert to a Slate point.

Returns

    Returns Point | undefined - The corresponding Slate point if found, or undefined if not found.

toSlateRange

Find a Slate range from a DOM range.

Parameters

Collapse all

    The DOM range to convert to a Slate range.

Returns

    Returns Range | undefined - The corresponding Slate range if found, or undefined if not found.

Query Operations

hasBlocks

Check if a node has block children.

Parameters

Collapse all

    The node to check for block children.

Returns

    Returns boolean - true if the node has block children, false otherwise.

hasInlines

Check if a node has inline children.

Parameters

Collapse all

    The node to check for inline children.

Returns

    Returns boolean - true if the node has inline children, false otherwise.

hasTexts

Check if a node has text children.

Parameters

Collapse all

    The node to check for text children.

Returns

    Returns boolean - true if the node has text children, false otherwise.

isBlock

Check if a value is a block element.

Parameters

Collapse all

    The value to check for block element type.

Returns

    Returns boolean - true if the value is a block element, false otherwise.

isEdgePoint

Check if a point is an edge of a location.

Parameters

Collapse all

    The point to check for edge position.

    The location to check the edge of.

Returns

    Returns boolean - true if the point is at the start or end edge of the location, false otherwise.

isEmpty

Check if a location is empty.

Parameters

Collapse all

    The location to check for emptiness. Defaults to current selection.

Returns

    Returns boolean - true if the location is empty, false otherwise.

isEnd

Check if a point is the end of a location.

Parameters

Collapse all

    The point to check for end position.

    The location to check the end of.

Returns

    Returns boolean - true if the point is at the end of the location, false otherwise.

isStart

Check if a point is the start of a location.

Parameters

Collapse all

    The point to check for start position.

    The location to check the start of.

Returns

    Returns boolean - true if the point is at the start of the location, false otherwise.

isElementReadOnly

Check if an element is read-only.

Parameters

Collapse all

    The element to check for read-only status.

Returns

    Returns boolean - true if the element is read-only, false otherwise.

isVoid

Check if an element is void.

Parameters

Collapse all

    The element to check.

Returns

    Returns boolean - true if the element is void, false otherwise.

markableVoid

Check if an element is a markable void element.

Parameters

Collapse all

    The element to check for markable void status.

Returns

    Returns boolean - true if the element is a markable void, false otherwise.

// Note: Using this incorrectly can leave the editor in an invalid state.

Options

QueryOptions

Common options used across multiple query methods:

Parameters

Collapse all

    Location to start searching from. Defaults to current selection.

    Match the node by id. true will match all nodes with an id.

    Match block nodes.

    When true, match only empty nodes. When false, match only non-empty nodes.

    Match the node.

    When true, match only text nodes.

QueryMode

Parameters

Collapse all

    • '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