Selection API

SelectionApi is frozen. Compose a custom helper around it instead of mutating the namespace.

Editor reads

editor.read.selection() => Range | null

Read the active range or null. The same callable is available as state.selection() and tx.selection() inside read and update callbacks. The returned object contains only anchor and focus; it has no selection-kind tag or plugin payload.

Use it directly wherever a Slate Range is expected.

For a node selection, selection() returns the directed representative range between its anchor and focus nodes. Read exact disjoint membership with selection.nodes() and one exact range per node with selection.ranges(). Range predicates such as selection.isExpanded(), isWithinBlock(), and isAcrossBlocks() inspect that same representative range. Use nodes() for exact node-selection membership instead of treating those predicates as a selection-kind test.

editor.read.selection.nodeMode() => NodeSelectionMode | null

Read how the current node selection was made: 'block' for block gestures or 'object' for one selected object. Text selections and a missing selection return null. Use state.selection.nodeMode() or tx.selection.nodeMode() inside a read or update callback.

editor.read.selection.ranges() => readonly Range[]

Read every exact range in the current selection. Text selections return one range and node selections return one range per selected path. Each result is a plain Range. A missing selection returns an empty array.

Use state.selection.ranges() or tx.selection.ranges() inside a read or update callback.

Editor updates

editor.update.selection.setNodes(targets, options?)

Select live nodes by Path, NodeKey, or live descendant. The editor resolves every target in one root, sorts and deduplicates the paths, and drops descendants of selected ancestors. An empty collection clears the selection. A missing or foreign target rejects the whole update.

Pass { anchor, focus } when gesture direction matters. Both endpoints must be members of the exact selected targets. Omit them for deterministic document-order endpoints.

mode defaults to 'block'. Pass { mode: 'object' } when the user selected one object itself, such as an image or focused media controls. An object selection must hold one selectable element that is not void and whose schema marks it object or atom; any other target rejects the update.

Use tx.selection.setNodes(targets) when earlier writes in the same transaction create or move the targets.

Static methods

SelectionApi.equals(left: Selection, right: Selection) => boolean

Compare complete text or node selection values.

SelectionApi.isSelection(value: unknown) => value is SelectionValue

Strictly check either built-in serializable selection shape. This predicate does not verify whether its points or paths exist in a document.

SelectionApi.isText(value: unknown) => value is TextSelection

Strictly check the built-in text-selection shape. Insertion marks are valid only on a collapsed text selection.

SelectionApi.isNode(value: unknown) => value is NodeSelection

Strictly check the built-in node-selection shape and canonical path membership.

SelectionApi.root(selection) => NamedRootKey | undefined

Read the named root declared by a text or node selection. A primary-root selection returns undefined.

SelectionApi.text(range: Range, options?) => TextSelection

Create a text selection from a range and optional affinity or insertion marks.

SelectionApi.nodes(paths: readonly [Path, ...Path[]], options) => NodeSelection

Create a detached node selection. options.mode is required: 'block' or 'object'. Paths are non-empty, deduplicated, and sorted in document order. Descendants of selected ancestors are removed. An 'object' selection holds exactly one path after that. anchorPath and focusPath preserve direction and must both be exact members. Live editor code uses selection.setNodes(targets, { anchor, focus, mode }) instead.

Mapping keeps an object selection while its node survives as an object, and turns it into a block selection when the node stops being one.

Read exact selected entries with editor.read.selection.nodes() or tx.selection.nodes(). Use editor.read.nodes.blocks() to project the active selection to schema blocks. ranges() projects one range per selected node, while contains and intersects evaluate those exact projections.

Editor validation

state.selection.isValid(value: unknown) => value is Selection

Validate a complete built-in selection against the current document. The direct read form is editor.read.selection.isValid(value).

This check accepts null, rejects unknown kinds, and verifies every text point or exact node path against its document root.

In Plate React, node selection is model-only: selection() still exposes its active model range while the editor remains focused and the native browser selection has no range. See Object elements with editable children for asset focus, child-content navigation, and deletion.

Plate React apps can render selected-block highlights and blank-space drag selection with the Node Selection components.