---
title: "Selection awareness"
description: "Make the AI aware of the selected content in the editor."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/selection-awareness"
---

# Selection awareness

Make the AI aware of the selected content in the editor.

- **1. Get access**

  Access the AI Toolkit extension by purchasing the paid AI Toolkit add-on.
  Contact our team.
- **2. Access the private registry**

  The AI Toolkit extension is published in Tiptap's private npm registry. Authenticate to
  Tiptap's private npm registry by following the [setup guide](https://tiptap.dev/docs/guides/pro-extensions.md).
- **3. Install the extension**

  Install the extension from the private registry using npm or your preferred package manager.

Configure the AI so that it can read and edit the selected content in the editor.

> **Continuation from the AI agent chatbot guide:**
>
> This guide continues the [AI agent chatbot
> guide](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/agents/ai-agent-chatbot.md). Read it first.

> **Interactive demo:** [selection awareness](https://ai-toolkit-demos.vercel.app/selection-awareness)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## The `tiptapReadSelection` tool

The `tiptapReadSelection` tool allows the AI agent to read the selected content in the editor.

It is included by default in the list of tool definitions that are passed to the AI model.

```ts
// Server-side code
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'

const definitions = toolDefinitions({
  // Enable the tiptapReadSelection tool.
  // The tiptapReadSelection tool is enabled by default.
  tiptapReadSelection: true,
})
```

The tool can then be executed in the client-side using the `executeTool` method. It does not require any parameters.

```ts
// Client-side code
const toolkit = getAiToolkit(editor)
const result = await toolkit.executeTool({
  toolName: 'tiptapReadSelection',
})
```

The output of the tool contains the following information:

- The content of the selection
- The position of the selection

This information lets the AI know what content is selected, and where it is located in the document, so that it can edit it later.

If reading and writing the selection is not a requirement of your app, you can disable the tool by passing `false` to the `tiptapReadSelection` option in the tool definitions.

```ts
// Server-side code
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'

const definitions = toolDefinitions({
  // Disable the tiptapReadSelection tool.
  tiptapReadSelection: false,
})
```

## Preserving the selection

Sometimes, while the AI is doing its work, the user changes the selection in the editor. This confuses the AI: when it has finished deciding what to do, it does not know that the selection has changed, so it reads the wrong selection content.

To avoid this, you can store the selection when the user sends a message to the AI, so that it does not change while the AI is thinking (even if the user changes it afterwards).

First, call the `setActiveSelection` method with the current selection when the user sends a message to the AI.

```ts
const toolkit = getAiToolkit(editor)
// Call this method just before the AI starts working.
toolkit.setActiveSelection(editor.state.selection)
```

Then, when the AI finishes its work, call the `setActiveSelection` method with `null` to unset the active selection.

```ts
toolkit.setActiveSelection(null)
```

You can also set the active selection to any position in the document.

```ts
toolkit.setActiveSelection({ from: 10, to: 20 })
```

## Recommended model and reasoning effort configuration

The `readSelection` tool informs the AI about the selected content but it does not force it to only edit the selection. Therefore, the AI model might edit the surrounding paragraph instead of just the selected content.

In our testing, we've found that models with reasoning enabled (like, for example, `gpt-5.4-mini` with reasoning effort set to `low`) perform better at keeping their edits scoped to the selection when told to do so.

Another option is to implement the [insert content workflow](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/workflows/insert-content.md) instead. This workflow can be used to restrict the editable area, so the AI can strictly only re-write the selection.

## End result

With additional CSS styles, the result is a simple but polished AI chatbot that can edit the selected content:

> **Interactive demo:** [selection awareness](https://ai-toolkit-demos.vercel.app/selection-awareness)

See the [source code on GitHub](https://github.com/ueberdosis/ai-toolkit-demos).

## Next steps

- Learn more about the `getActiveSelection` and `setActiveSelection` methods in the [API reference](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/execute-tool.md#setactiveselection).