Editor API

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.

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:

// 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:

// 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.

OptionsQueryMode

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

    Example:

    // 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.

OptionsQueryOptions<V>

Collapse all

    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.

OptionsEditorAboveOptions<V>

Collapse all

    Common query options.

    Query mode options.

    Whether to include void nodes in the search.

ReturnsNodeEntry<N> | undefined

    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.

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

OptionsEditorBlockOptions<V>

Collapse all

    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.

ReturnsNodeEntry<N> | undefined

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

blocks

Returns all matching blocks.

OptionsEditorNodesOptions<V>

Collapse all

    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.

ReturnsNodeEntry<ElementIn<V>>[]

    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.

OptionsEditorNodesOptions<V>

Collapse all

    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.

Returns[NodeEntry<N1>, NodeEntry<N2>] | null

    A tuple of [startBlock, endBlock] above the location, or null if not found.

first

Get the first node at a location.

Parameters

Collapse all

    The location to get the first node from.

ReturnsNodeEntry<DescendantIn<V>> | undefined

    A tuple containing the first node and its path, or undefined if not found.

fragment

Get the fragment at a location or selection.

Parameters

Collapse all

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

    Options for extracting and processing the fragment.

OptionsEditorFragmentOptions

Collapse all

    Types of structural nodes to unwrap.

ReturnsElementOrTextIn<V>[] | undefined

    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.

Parameters

Collapse all

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

ReturnsElementOrTextIn<V>[]

    The fragment at the current selection.

hasBlocks

Check if a node has block children.

Parameters

Collapse all

    The element to check.

Returnsboolean

    True if the element has block children, false otherwise.

hasInlines

Check if a node has inline and text children.

Parameters

Collapse all

    The element to check.

Returnsboolean

    True if the element has inline and text children, false otherwise.

hasMark

Check if mark is active at selection.

Parameters

Collapse all

    The mark key to check.

Returnsboolean

    True if the mark is active at the current selection, false otherwise.

hasPath

Check if a path exists in the editor.

Parameters

Collapse all

    The path to check.

Returnsboolean

    True if the path exists, false otherwise.

hasTexts

Check if a node has text children.

Parameters

Collapse all

    The element to check.

Returnsboolean

    True if the element has text children, 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 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

Optionsobject

Collapse all

    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.

Returnsboolean

    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).

Returnsboolean

    True if the selection is collapsed, false otherwise.

isEdge

Check if a point is an edge of a location.

Parameters

Collapse all

    The point to check.

    The location to check against. Defaults to current selection.

Returnsboolean

    True if the point is an edge of the location, false otherwise.

isEditorEnd

Check if selection is at editor end.

Returnsboolean

    True if the selection is at the editor end, false otherwise.

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

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

    Options for determining emptiness.

OptionsEditorEmptyOptions

Collapse all

    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.

Parameters

Collapse all

    The point to check.

    The location to check against. Defaults to current selection.

Returnsboolean

    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).

Returnsboolean

    True if the selection is expanded, false otherwise.

isNormalizing

Check if the editor is currently normalizing after each operation.

Returnsboolean

    True if the editor is currently normalizing, false otherwise.

isStart

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

Parameters

Collapse all

    The point to check.

    The location to check against. Defaults to current selection.

Returnsboolean

    True if the point is the start point of the location, false otherwise.

isSelected

Check if a path is selected by the current selection.

Parameters

Collapse all

    The path or range to check.

    Options for checking selection.

OptionsEditorIsSelectedOptions

Collapse all

    Check if selection contains the entire path range.

Returnsboolean

    True if the path is selected, false otherwise.

leaf

Get the leaf text node at a location.

Parameters

Collapse all

    The location to get the leaf from.

    Options for getting the leaf.

OptionsEditorLeafOptions

Collapse all

    The depth to traverse to find the leaf.

    Which edge of the location to get the leaf from ('start' | 'end').

ReturnsNodeEntry<TextIn<V>> | undefined

    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.

OptionsEditorLevelsOptions<V>

Collapse all

    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.

ReturnsGenerator<NodeEntry<NodeIn<V>>, void, undefined>

    A generator that yields tuples of [node, path] for each ancestor level.

last

Get the last node at a location.

Parameters

Collapse all

    The location to get the last node from.

    Options for getting the last node.

OptionsEditorLastOptions

Collapse all

    Get last node at this level (0-based).

ReturnsNodeEntry<DescendantIn<V>> | undefined

    A tuple containing the last node and its path, or undefined if not found.

mark

Returns the selection mark value by key.

Parameters

Collapse all

    The mark key.

ReturnsMarksIn<V>[K] | null | undefined

    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.

ReturnsMarksIn<V> | null

    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.

OptionsEditorNextOptions<V>

Collapse all

    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

ReturnsNodeEntry<DescendantIn<V>> | undefined

    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.

Parameters

Collapse all

    The location to get a node from.

    Options for getting a node.

OptionsEditorNodeOptions

Collapse all

    The depth to traverse to find the node.

    Which edge of the location to get the node from.

ReturnsNodeEntry<NodeIn<V>> | undefined

    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.

OptionsEditorNodesOptions<V>

Collapse all

    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.

ReturnsGenerator<NodeEntry<DescendantIn<V>>, void, undefined>

    A generator that yields tuples of [node, path] for each matching node.

parent

Get the parent node of a location.

Parameters

Collapse all

    The location to get the parent from.

    Options for getting the parent node.

OptionsEditorParentOptions

Collapse all

    Number of levels to traverse up to find the parent.

    Which edge of the location to get the parent from.

ReturnsNodeEntry<AncestorIn<V>> | undefined

    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.

OptionsEditorPreviousOptions<V>

Collapse all

    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

ReturnsNodeEntry<DescendantIn<V>> | undefined

    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.

OptionsEditorPropOptions<V>

Collapse all

    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

Returnsstring | undefined

    The consistent property value across all nodes, or undefined if values differ.

string

Get the text string content of a location.

Parameters

Collapse all

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

    Options for getting text content.

OptionsEditorStringOptions

Collapse all

    Whether to include text content from void nodes.

Returnsstring

    The text content at the specified location.

void

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

OptionsEditorVoidOptions

Collapse all

    The location to search from. Defaults to current selection.

    Query mode for matching nodes.

    Whether to include void nodes in the search.

ReturnsNodeEntry<ElementIn<V>> | undefined

    A tuple containing the void node and its path, or undefined if not found.

Location

findPath

Find the path of a Slate node in the editor.

Parameters

Collapse all

    The node to find the path for in the editor tree.

    Options for finding the node's path.

OptionsEditorFindPathOptions

Collapse all

    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.

ReturnsPath | undefined

    The path of the node if found, undefined otherwise.

path

Get the path of a location.

Parameters

Collapse all

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

ReturnsPath

    The path of the location.

point

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

Parameters

Collapse all

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

    Options for getting the point.

OptionsEditorPointOptions

Collapse all

    Which edge of the location to get the point from.

ReturnsPoint

    The point at the specified location and edge.

positions

Iterate through all possible point positions in the document.

OptionsEditorPositionsOptions

Collapse all

    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.

ReturnsGenerator<Point, void, undefined>

    A generator that yields each valid point position in the document.

nodesRange

Returns the range spanning the given node entries.

Parameters

Collapse all

    The node entries to get the range for.

ReturnsTRange | undefined

    The range spanning the nodes, or undefined if no valid range can be created.

range

Create a range between two locations.

OptionsEditorRangeOptions

Collapse all

    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.

ReturnsTRange

    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.

    Options for getting the start point.

OptionsEditorStartOptions

Collapse all

    Get the start point of the next node instead of the current one.

ReturnsPoint

    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).

Parameters

Collapse all

    The range to unhang.

    Options for un-hanging the range.

OptionsEditorUnhangRangeOptions

Collapse all

    Allow placing the end of the selection in a void node.

ReturnsTRange

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

Element

elementReadOnly

Check if an element is read-only.

Parameters

Collapse all

    The element to check for read-only status.

Returnsboolean

    True if the element is read-only, false otherwise.

isBlock

Check if a value is a block Element object.

Parameters

Collapse all

    The value to check.

Returnsboolean

    True if the value is a block element, false otherwise.

isInline

Check if a value is an inline Element object.

Parameters

Collapse all

    The element to check.

Returnsboolean

    True if the element is inline, false otherwise.

isSelectable

Check if a value is a selectable Element object.

Parameters

Collapse all

    The element to check.

Returnsboolean

    True if the element is selectable, false otherwise.

isVoid

Check if an element is void.

Parameters

Collapse all

    The element to check for void status.

Returnsboolean

    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.

Returnsboolean

    True if the element is a markable void element, false otherwise.

Ref

pathRef

Create a mutable ref for a Path.

Parameters

Collapse all

    The path to reference.

    Options for the path reference.

OptionsEditorPathRefOptions

Collapse all

    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

ReturnsPathRef

    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.

ReturnsSet<PathRef>

    The set of tracked path refs.

pointRef

Create a mutable ref for a Point.

Parameters

Collapse all

    The point to reference.

    Options for the point reference.

OptionsEditorPointRefOptions

Collapse all

    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

ReturnsPointRef

    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.

ReturnsSet<PointRef>

    The set of tracked point refs.

rangeRef

Create a mutable ref for a Range.

Parameters

Collapse all

    The range to reference.

    Options for the range reference.

OptionsEditorRangeRefOptions

Collapse all

    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

ReturnsRangeRef

    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.

ReturnsSet<RangeRef>

    The set of tracked range refs.

DOM

findDocumentOrShadowRoot

Find the document or shadow root from the editor.

ReturnsDocument | ShadowRoot

    The document or shadow root containing the editor.

findEventRange

Get the target range from a DOM event.

Parameters

Collapse all

    The DOM event to get the range from.

ReturnsTRange | null

    The range at the event target, or null if no valid range found.

findKey

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

Parameters

Collapse all

    The node to find the key for.

ReturnsKey

    The key associated with the node.

getWindow

Get the window object from the editor.

ReturnsWindow

    The window object associated with the editor.

hasDOMNode

Check if a DOM node is within the editor.

Parameters

Collapse all

    The DOM node to check.

    Options for checking the DOM node.

Optionsobject

Collapse all

    Whether to check if the node is in an editable element.

Returnsboolean

    True if the DOM node is within the editor, false otherwise.

hasEditableTarget

Check if a DOM target is editable.

Parameters

Collapse all

    The DOM target to check.

Returnstarget is Node

    True if the target is editable, false otherwise.

hasRange

Check if the editor has a range.

Parameters

Collapse all

    The range to check.

Returnsboolean

    True if the editor has the specified range, false otherwise.

hasSelectableTarget

Check if a DOM target is selectable.

Parameters

Collapse all

    The DOM target to check.

Returnstarget is Node

    True if the target is selectable, false otherwise.

hasTarget

Check if a DOM target exists.

Parameters

Collapse all

    The DOM target to check.

Returnstarget is Node

    True if the target exists, false otherwise.

isComposing

Check if the user is currently composing inside the editor.

Returnsboolean

    True if the user is currently composing text, false otherwise.

isFocused

Check if the editor is focused.

Returnsboolean

    True if the editor has focus, false otherwise.

isReadOnly

Check if the editor is in read-only mode.

Returnsboolean

    True if the editor is read-only, false otherwise.

toDOMNode

Find the native DOM element from a Slate node.

OptionsTNode

Collapse all

    The Slate node to convert to a DOM element.

ReturnsHTMLElement

    The corresponding DOM element for the Slate node.

toDOMPoint

Find a native DOM selection point from a Slate point.

OptionsPoint

Collapse all

    The Slate point to convert to a DOM point.

ReturnsDOMPoint

    A tuple of [node, offset] representing the DOM point.

toDOMRange

Find a native DOM range from a Slate range.

OptionsTRange

Collapse all

    The Slate range to convert to a DOM range.

ReturnsDOMRange

    The corresponding DOM range for the Slate range.

toSlateNode

Find a Slate node from a native DOM element.

OptionsDOMNode

Collapse all

    The DOM node to convert to a Slate node.

ReturnsTNode | undefined

    The corresponding Slate node if found, undefined otherwise.

toSlatePoint

Find a Slate point from a DOM selection point.

OptionsDOMPoint

Collapse all

    The DOM point to convert to a Slate point.

ReturnsPoint | undefined

    The corresponding Slate point if found, undefined otherwise.

toSlateRange

Find a Slate range from a DOM range.

OptionsDOMRange

Collapse all

    The DOM range to convert to a Slate range.

ReturnsTRange | undefined

    The corresponding Slate range if found, undefined otherwise.

Callback

onChange

Called when there is a change in the editor.

Optionsobject

Collapse all

    The operation that triggered the change.

Core

getDirtyPaths

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

Parameters

Collapse all

    The operation that triggered normalization.

ReturnsPath[]

    An array of paths that need to be normalized after the operation.

setNormalizing

Manually control the editor's normalizing state.

Optionsboolean

Collapse all

    Whether the editor should normalize after each operation.

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.

Returnsboolean

    True if the previous node should be removed during merge, false if it should be kept.

shouldNormalize

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

Optionsobject

Collapse all

    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.

Returnsboolean

    True if the editor should normalize, false otherwise.

History

isMerging

Get the merge flag's current value.

Returnsboolean

    True if the editor is currently merging operations, false otherwise.

isSaving

Get the saving flag's current value.

Returnsboolean

    True if the editor is currently saving, false otherwise.

isSplittingOnce

Get the splitting flag's current value.

Returnsboolean

    True if the editor is currently performing a single split operation, false otherwise.

Utils

create.block

Default block factory for creating new block elements.

Parameters

Collapse all

    Partial element properties to merge into the new block.

    Path for the new block.

ReturnsTElement

    A new block element.

create.value

Default value factory for creating new editor values.

ReturnsValue

    A new editor value.