---
title: "Blok Selection API — ranges and cross-block"
description: "Read and manipulate the current selection, including selections that span more than one block."
source: https://blokeditor.com/docs/selection-api/
lastmod: 2026-09-07
---

Framework JavaScript

Editing Selection

On this page selection.findParentTag(tagName, className?)

# Selection API: read and set the selection

Work with text selection within the editor.

[Edit this page on GitHub](https://github.com/JackUait/blok/blob/main/docs/src/components/api/api-data.ts)

### 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 to 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 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

Heavier reset than `removeFakeBackground()` — clears both DOM and 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()` — the round-trip that lets inline tools survive a focus change.

TypeScript

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