Selection

Manages native selection ranges, select-all state, and DOM context queries around the caret.

Access:

app.getService('selection')

App code:

const selection = app.getService('selection');

Plugin:

const selection = this.app.getService('selection');

getSelection#

Returns the host window Selection object for the editor document.

Returns: Selection|null

selection.getSelection();

getRange#

Returns the first Range in the current selection, or null when no range exists.

Returns: Range|null

selection.getRange();

getRect#

Computes a bounding rectangle for the selection start or end, adjusting for fully selected elements and collapsed ranges.

Parameters:

• type (string) — block or entity type name

Returns: { top, bottom, left, right, width, height }|null

selection.getRect('end');

isRange#

Returns true when the current selection contains at least one range.

Returns: boolean

selection.isRange();

isSelectAll#

Returns true when the editor host has the select-all CSS class applied.

Returns: boolean

selection.isSelectAll();

selectAll#

Clears block focus, marks select-all state on the host, selects the entire editable root, and emits selection:selectall.

Returns: boolean

selection.selectAll();

deselectAll#

Clears select-all state, removes all native ranges, clears block focus, and emits selection:deselectall.

Returns: boolean

selection.deselectAll();

isCollapsed#

Returns true when the current range is collapsed to a caret.

Returns: boolean

selection.isCollapsed();

isBackwards#

Returns true when the selection focus point is at the range start (backwards selection).

Returns: boolean

selection.isBackwards();

truncate#

Deletes the contents of the given or current range, collapses it to the start, and applies it to the selection.

Parameters:

• range (any) — range

Returns: boolean

selection.truncate();

truncateIfNeeded#

Truncates the range only when it is not collapsed, then returns the updated range or the original collapsed range.

Parameters:

• range (any) — range

Returns: Range|null

selection.truncateIfNeeded();

collapse#

Collapses the current range to its start or end and updates the selection.

Parameters:

• where (any) — insert position relative to current block

Returns: boolean

selection.collapse('end');

select#

Creates a range selecting all contents of the element, focuses the host, and applies it to the selection.

Parameters:

• el (HTMLElement | string) — DOM element

Returns: boolean

selection.select(paragraphEl);

containsElement#

Returns true when the given range intersects the element.

Parameters:

• el (HTMLElement | string) — DOM element
• range (any) — range

Returns: boolean

selection.containsElement(el);

isRangeInsideElement#

Returns true when both range boundary containers are contained within the element.

Parameters:

• range (any) — range
• el (HTMLElement | string) — DOM element

Returns: boolean

selection.isRangeInsideElement(range, blockEl);

isInEditor#

Returns true when the selection range or current block is inside the editable editor root.

Returns: boolean

selection.isInEditor();

extractHtmlFromCaret#

Extracts a DocumentFragment of content from the caret position to the end of the element.

Parameters:

• el (HTMLElement | string) — DOM element

Returns: DocumentFragment|null

selection.extractHtmlFromCaret(blockEl);

isElementFullySelected#

Compares normalized selected text against the element text using includes or equals mode.

Parameters:

• el (HTMLElement | string) — DOM element
• options (object) — object with the keys below
  • mode (string) — comparison mode: 'includes' (default — selection text contains element text) or 'equals' (exact match)
  • equals (boolean) — shorthand for mode: 'equals' when set to true

Returns: boolean

selection.isElementFullySelected(el, { equals: true });

setRange#

Replaces all selection ranges with the given range.

Parameters:

• range (any) — range

Returns: boolean

selection.setRange(range);

saveSelection#

Stores the current range in an internal snapshot for later restore.

Returns: { range: Range }|null

const saved = selection.saveSelection();

restoreSelection#

Focuses the host and restores a previously saved range snapshot.

Parameters:

• saved (any) — saved

Returns: void

selection.restoreSelection(saved);

getText#

Returns the plain text content of the current selection.

Returns: string

selection.getText();

getHtml#

Returns the HTML of the current non-collapsed selection, or an empty string for collapsed or empty-paragraph selections.

Returns: string

selection.getHtml();

getNode#

Returns the selection focus node.

Returns: Node|null

selection.getNode();

getElement#

Returns the element at the caret or the parent element of a text node.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getElement();

getParentNode#

Returns the parent node of the caret node.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: Node|null

selection.getParentNode();

getClosest#

Returns the nearest ancestor element matching the CSS selector from the caret context.

Parameters:

• selector (string) — CSS selector
• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getClosest('a');

getInline#

Walks up from the caret to find the nearest inline tag defined in editor options.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getInline();

getBlock#

Walks up from the caret to find the nearest block tag defined in editor options.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getBlock();

getInlineElements#

Collects the chain of inline ancestor elements from the caret up to the editor root.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: { elements: HTMLElement[], bottom: HTMLElement|null, top: HTMLElement|null }

selection.getInlineElements();

getTopInline#

Returns the outermost inline ancestor in the caret inline chain.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getTopInline();

getDataBlock#

Returns the nearest ancestor element with a data-block attribute.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLElement|null

selection.getDataBlock();

getNodes#

Returns DOM nodes intersecting the current range, with optional type filters and select-all handling.

Parameters:

• options (object) — object with the keys below
  • types (Array) — node type filter: 'all' (default), 'links', 'inline', 'block', 'both', 'data-block', 'data-block-inline', 'data-block-no-inline', or an array of block type names
  • onlyLinks (boolean) — shorthand for types: 'links'
  • partial (boolean) — keep partially-intersected boundary nodes instead of only fully-contained ones
  • ignoreSelectAll (boolean) — collect nodes normally even when the whole editor is select-all'd
  • visible (boolean) — when true/false, only keep visible/hidden nodes (default: no filter)
  • topLevelBlocks (boolean) — only keep elements whose parent is the editor root (or a schema section)
  • allowLinks (boolean) — set to false to exclude <a> elements even when types would include them
  • tags (Array) — only keep elements matching these tag names
  • not (string) — CSS selector; elements matching it are excluded
  • notBlockTypes (Array) — exclude elements resolving to these block type names
  • onlyFullySelected (boolean) — only keep nodes whose text is fully covered by the range

Returns: Node[]

selection.getNodes({ types: 'links' });

getLinks#

Returns unique anchor elements from the inline chain and selected nodes, sorted in document order.

Parameters:

• from (Block | HTMLElement) — starting block for traversal

Returns: HTMLAnchorElement[]

selection.getLinks();