Tiptap Docs

Suggestions

When the AI makes changes to the document, you can display them as suggestions. This way, the user can review the changes and accept or reject them.

What are suggestions?

A suggestion is a proposed change to the document. Every Suggestion object has these properties:

  • id (string): A unique identifier for the suggestion.
  • range (Range): This is the position of the suggestion. It has a from property (the place where the suggestion starts) and a to property (the place where the suggestion ends). Learn more about ranges in the Concepts guide.
  • The content that the AI suggests inserting into that range. This content is stored in the replacementOptions property.

See all the properties of the Suggestion object in the API reference.

Two types of suggestions

There are two types of suggestions:

  • Preview mode: When the change is previewed before applying it. The document is not modified until the user accepts the suggestion.
  • Review mode: When the change is reviewed after applying it. The document has already been modified and the suggestion allows the user to undo the change.

How to generate suggestions?

Suggestions are generated when you call a method of the AI Toolkit that edits the document (see the API reference).

These methods can be configured in three different ways:

Option 1: Update the document directly

The default behaviour of AI Toolkit methods is to edit the document directly and not generate any suggestions.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  // No reviewOptions property
})

Option 2: Generate suggestions before editing the document

This approach does not modify the document and generates suggestions in preview mode.

The document is edited only if the user accepts the suggestions.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  reviewOptions: { mode: 'preview' },
})

Option 3: Generate suggestions after editing the document

This approach modifies the document directly and generates suggestions in review mode. These suggestions allow the user to undo the change by applying the suggestion.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  reviewOptions: { mode: 'review' },
})

Diff modes

Suggestions are generated by comparing the document before and after the change.

You can configure how the comparison is performed with the diffUtilityConfig property of the reviewOptions object.

This allows you to compare changes character by character or block by block.

toolkit.executeTool({
  toolName: 'tiptapEdit',
  input: {},
  reviewOptions: {
    mode: 'review',
    diffUtilityConfig: { mode: 'block' },
  },
})

There are three diff modes:

  • detailed (default): Shows precise character-level changes within text.
  • block: Groups changes by paragraphs and headings, instead of individual characters.
  • smartInline: Experimental mode that behaves like detailed but with more accurate results.

The diff utility has other options, learn about them in the API reference.

Accepting and rejecting suggestions

You can accept and reject suggestions by calling the acceptSuggestion and rejectSuggestion methods.

toolkit.acceptSuggestion('suggestion-1')
toolkit.rejectSuggestion('suggestion-1')

These methods return AI feedback that you can collect and send to the AI to improve future suggestions.

const result = toolkit.acceptSuggestion('suggestion-1')
// result.aiFeedback.events

You can also accept and reject all suggestions at once by calling the acceptAllSuggestions and rejectAllSuggestions methods.

Suggestions can also be read and updated programmatically. See the API reference for all available methods.

Next steps

PreviouslyConcepts