Selectors API overview

Selectors are pure functions that derive state from the editor snapshot. They provide a clean way to access editor state without directly parsing the snapshot structure.

import * as selectors from '@portabletext/editor/selectors'

Selectors are commonly used for creating behaviors and toolbar components.

Create a behavior Custom behaviors let you control how the editor reacts to events and input.

Customize the toolbar Create custom toolbar components for your editor.

Note

Unsure what a “span” is or what “focus” means in this context? Check the common terms section.

Condition selectors

Condition selectors return a boolean or truthy value based on the current editor state.

Active state conditions

• isActiveAnnotation(name) - Returns true if the specified annotation is active in the selection
• isActiveDecorator(name) - Returns true if the specified decorator is active in the selection
• isActiveListItem(name) - Returns true if the specified list type is active
• isActiveStyle(name) - Returns true if the specified style is active

Selection conditions

• isSelectionCollapsed - Returns true if the selection is collapsed (cursor with no range)
• isSelectionExpanded - Returns true if the selection spans multiple characters

Position conditions

• isAtTheStartOfBlock - Returns true if the cursor is at the start of a block
• isAtTheEndOfBlock - Returns true if the cursor is at the end of a block
• isSelectingEntireBlocks - Returns true if entire blocks are selected

Range conditions

• isOverlappingSelection - Returns true if selections overlap
• isPointBeforeSelection - Returns true if a point is before the current selection
• isPointAfterSelection - Returns true if a point is after the current selection

Block selectors

Retrieve block-level elements from the editor.

Navigation

• getFirstBlock - Get the first block in the editor
• getLastBlock - Get the last block in the editor
• getNextBlock - Get the block after the current focus block
• getPreviousBlock - Get the block before the current focus block

Focus & anchor

• getAnchorBlock - Get the block where the selection anchor is located
• getFocusBlock - Get the block where the selection focus is located

Selection range

• getSelectedBlocks - Get all blocks within the current selection
• getSelectionStartBlock - Get the block at the start of the selection
• getSelectionEndBlock - Get the block at the end of the selection

Text block selectors

Retrieve text blocks specifically (excludes block objects).

• getAnchorTextBlock - Get the text block where the selection anchor is located
• getFocusTextBlock - Get the text block where the selection focus is located
• getSelectedTextBlocks - Get all text blocks within the current selection
• getFocusListBlock - Get the list block where focus is located (if in a list)

Span selectors

Retrieve span elements (text segments within blocks).

• getAnchorSpan - Get the span where the selection anchor is located
• getFocusSpan - Get the span where the selection focus is located
• getNextSpan - Get the span after the current focus span
• getPreviousSpan - Get the span before the current focus span
• getSelectedSpans - Get all spans within the current selection

Child selectors

Retrieve child elements within blocks.

• getAnchorChild - Get the child element where the selection anchor is located
• getFocusChild - Get the child element where the selection focus is located
• getSelectionStartChild - Get the child at the start of the selection
• getSelectionEndChild - Get the child at the end of the selection

Inline object selectors

Retrieve inline objects (custom elements embedded in text).

• getFocusInlineObject - Get the inline object at the current focus position
• getNextInlineObject - Get the next inline object after focus
• getNextInlineObjects - Get all inline objects after focus
• getPreviousInlineObject - Get the previous inline object before focus
• getPreviousInlineObjects - Get all inline objects before focus

Block object selectors

Retrieve block objects (custom block-level elements).

• getFocusBlockObject - Get the block object at the current focus position

Selection selectors

Get information about the current selection.

• getSelection - Get the current selection (anchor and focus points)
• getSelectionText - Get the text content of the current selection
• getSelectedValue - Get the Portable Text value of the selected content
• getSelectionStartPoint - Get the starting point of the selection
• getSelectionEndPoint - Get the ending point of the selection
• getCaretWordSelection - Get the word selection at the caret position

Active state selectors

Get information about active formatting and marks.

• getActiveAnnotations - Get all active annotations in the selection
• getActiveListItem - Get the active list item type
• getActiveStyle - Get the active block style
• getMarkState - Get comprehensive mark state information for the selection

Text position selectors

Get text content relative to the cursor position.

• getBlockTextBefore - Get text in the current block before the cursor
• getBlockTextAfter - Get text in the current block after the cursor
• getBlockOffsets - Get character offsets within the current block

Value selectors

Access the editor value.

• getValue - Get the complete Portable Text value from the editor