Tiptap Docs

Selection awareness

Paid add-onBeta

Make AI aware of the user's selected content, so it can edit it.

Continuation from the AI agent chatbot guide

This guide continues the AI agent chatbot guide. Read it first.

See the source code on GitHub.

The readSelection tool

With the readSelection tool, the AI can read the user's selection. This tool only works with Tiptap Cloud collaborative documents.

Enable it in the fetch-tools request alongside the other tools:

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/fetch-tools`, {
  method: 'POST',
  headers: await getAuthHeaders(),
  body: JSON.stringify({
    editorContext,
    tools: {
      readSelection: true,
      // Other tools
      tiptapRead: true,
      tiptapEdit: true,
    },
  }),
})

The readSelection tool reads the selection of a single user. This is usually the user who prompts the AI. Pass the user ID as the tool.config.user parameter when the tool is executed. The developer passes this parameter, so the AI does not generate it.

In the chatbot guide's executeTool helper, add a selectionUserId: string parameter and include config: { user: selectionUserId } in the request's tool object. Pass the same user ID from the chat handler on each call. If the editor uses a collaborative field other than default, also send its name as field.

For example, the resulting readSelection request is:

const response = await fetch(`${apiBaseUrl}/v4/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: await getAuthHeaders(documentId),
  body: JSON.stringify({
    editorContext,
    document: { type: 'cloud', id: documentId },
    tool: {
      name: 'readSelection',
      // The AI calls the readSelection tool with no input parameters
      input: {},
      // The user's ID is passed by the developer
      config: { user: 'user-1' },
    },
  }),
})

See the REST API reference for more details about the tool.

Publish the selection to awareness

The server reads the selection from live collaboration awareness data. To make this data available, configure the CollaborationCaret extension and give the user an id that matches the tool.config.user you send to the server.

CollaborationCaret needs the provider, which the chatbot guide creates inside an effect. Store the provider in state, then add the caret once it exists:

import { CollaborationCaret } from '@tiptap/extension-collaboration-caret'

const [provider, setProvider] = useState<TiptapCollabProvider | null>(null)

// In the connection effect, call `setProvider(...)` with the new TiptapCollabProvider.

const editor = useEditor(
  {
    immediatelyRender: false,
    extensions: [
      StarterKit,
      Collaboration.configure({ document: doc }),
      ServerAiToolkit,
      ...(provider
        ? [
            CollaborationCaret.configure({
              provider,
              // The id is what readSelection matches against on the server.
              user: { id: 'user-1', name: 'You', color: '#6a00f5' },
            }),
          ]
        : []),
    ],
  },
  // Recreate the editor when the provider is ready, so the caret can attach.
  [provider],
)

Preserving the selection

The server reads the selection from awareness at the moment the tool runs. With @tiptap/y-tiptap 3.1.0 or later, the editor keeps its last selection in awareness when it loses focus, so users can select text and then type in chat. Each collaborative field keeps its own last selection.

With older versions, CollaborationCaret clears the awareness selection when the editor loses focus. Re-focus the editor when the user sends a message so it re-publishes the current selection:

const handleSubmit = () => {
  if (!input.trim()) return
  // Re-publish the selection to awareness: moving to the chat input blurred the
  // editor and cleared the awareness cursor.
  editor.commands.focus()
  sendMessage({ text: input })
  setInput('')
}

End result

With additional CSS styles, the result is a chatbot that can edit the user's selection:

See the source code on GitHub.

Limitations

Only works with Tiptap Cloud documents

The readSelection tool reads the selection state from the live updates sent by the CollaborationCaret extension. Therefore, it only works with Tiptap Cloud collaborative documents and is not compatible with documents provided inline.

AI model behavior

readSelection tells the AI what content is selected, but it does not force it to edit only the selection. Smaller, less capable AI models may rewrite the surrounding paragraph instead of just the selected span, especially for a sub-sentence selection.

In our testing, models with reasoning enabled (for example, gpt-5.6-luna with reasoning effort set to low) keep their edits scoped to the selection more reliably. A clear instruction such as "edit only the selected text" also helps.

Next steps

PreviouslyWith Whiteboard