Skip to content
FrameworkJavaScript

Selection API: read and set the selection

Work with text selection within the editor.

Last updated Sep 8, 2026Edit this page on GitHub

Reaching the editor instance

The methods below run on the editor you created with new Blok(). They are available once editor.isReady resolves.

TypeScript
// You already hold the instance returned by the constructor.
const editor = new Blok({ holder: 'editor' });
await editor.isReady;

// Call any API method on it.
editor.caret.setToLastBlock('end');

Methods

selection.findParentTag(tagName, className?)

HTMLElement | null

Find the parent element of the current selection matching the tag and optionally class.

When to use

The standard way for inline tools to detect whether the cursor is already inside their tag (e.g. an <a> for a link).

TypeScript
const bold = editor.selection.findParentTag('B');
if (bold) {
  console.log('Selection is inside bold text');
}

const link = editor.selection.findParentTag('A', 'external-link');

selection.expandToTag(node)

void

Expand selection to cover the entire element.

When to use

Grow the selection to wrap a whole element. Typically you select an existing mark before replacing or removing it.

TypeScript
const element = editor.selection.findParentTag('B');
if (element) {
  editor.selection.expandToTag(element);
  // Now entire bold element is selected
}

selection.setFakeBackground()

void

Set a fake background to imitate selection when focus moves away. Useful for inline tools.

When to use

Keep a visible 'selection' highlight while focus moves to your tool's input. Always pair with a later removeFakeBackground().

TypeScript
// Save selection visual before opening a modal
editor.selection.setFakeBackground();
// Open modal - selection stays visually highlighted

selection.removeFakeBackground()

void

Remove the fake background selection.

When to use

Tears down the fake highlight set by setFakeBackground(). Call it when your inline UI closes.

TypeScript
// After closing modal
editor.selection.removeFakeBackground();

selection.clearFakeBackground()

void

Clear all fake background state: both DOM elements and internal flags.

When to use

A heavier reset than removeFakeBackground(). It clears both the DOM and the internal flags if state got out of sync.

TypeScript
// Full cleanup after undo/redo
editor.selection.clearFakeBackground();

selection.save()

void

Save the current selection range to restore later.

When to use

Stash the current range before focus leaves the document (e.g. opening a dialog), then bring it back with restore().

TypeScript
// Save selection before moving focus
editor.selection.save();

// Do something that moves focus away...

// Restore selection
editor.selection.restore();

selection.restore()

void

Restore a previously saved selection range.

When to use

Re-applies the range saved by save(). This round-trip lets inline tools survive a focus change.

TypeScript
editor.selection.save();
// ... operations that move focus ...
editor.selection.restore();