> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Selection

> Read the selection, and keep it while your own UI takes focus.

The selection is exposed as blocks and offsets, marks, comment IDs, and
suggestion IDs. It never includes canvas geometry, so your UI does not depend on
how Revise lays out text.

## Reading

```ts theme={null}
const snapshot = editor.selection.getSnapshot();

snapshot.empty;            // caret rather than a range
snapshot.text;             // the selected text
snapshot.target;           // portable ranges for comments and formatting
snapshot.selectionTarget;  // explicit start/end for insert and replace
snapshot.activeMarks;      // ["bold", "italic"]
snapshot.activeCommentIds;
snapshot.activeChangeIds;
```

Subscribe to follow it:

```ts theme={null}
useEffect(() => editor.selection.observe(setSelection), [editor]);
```

`observe()` publishes the snapshot. `subscribe()` publishes `{ snapshot }`.
Both return an unsubscribe function. Both are memoized, so an identical
selection does not re-render your UI.

## Capture and restore

When the user clicks into an input in your own UI, such as a comment popover,
the editor loses focus and the selection is lost. Capture it first and restore
it afterward.

```ts theme={null}
const capture = editor.selection.capture();
// The user types in your popover. The editor loses focus.
const result = editor.selection.restore(capture);

if (!result.success) {
  // The captured blocks were moved or deleted.
}
```

`capture()` returns a frozen snapshot scoped to the current document. It stays
valid after focus moves away. It returns `null` when there is no selection or
caret.

`restore()` puts the selection back and refocuses the editor. It returns a
typed failure when:

* the editor is unavailable
* the document is read-only
* the capture belongs to a different document
* the captured blocks no longer exist (for example, after an agent edit)

<Tip>
  Capture when your UI opens and restore when it submits. A capture is scoped to
  one document and does not restore into another.
</Tip>

## Clearing

```ts theme={null}
editor.selection.clear();
```

## For agents

The `get_selection` tool returns the same snapshot to an agent: selected text,
caret or range positions, portable target segments, active formatting, comment
IDs, and suggestion IDs. It includes no geometry.

Your own agent does not receive the selection automatically. Give it
`get_selection` when it needs to act on the text the user selected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.