Tiptap Docs

Display suggestions

Suggestions are used to display the changes that the AI agent has made to the document. Each suggestion contains the following data:

  • The range of the document that has changed
  • The new content that should be inserted at that range. This content can be in different formats, like HTML, JSON, or plain text. There can also be multiple replacement options for the same range, and the user can choose which one to use.

The Suggestion object

A Suggestion represents a proposed change to a range of content in the editor, typically generated by an AI agent. It allows previewing, reviewing, and applying changes, and can include multiple replacement options.

Properties

  • id (string): A unique identifier for the suggestion.
  • range (Range): The range of content in the editor that the suggestion applies to.
  • rangeInOtherDoc? (Range): If this Suggestion was created by comparing this document with another, this property contains the range of the Change in the other document.
  • replacementOptions (ReplacementOption[]): One or more possible replacements for the selected range. The user can choose which option to apply. Each ReplacementOption can be one of the following types:
    • SliceReplacementOption (type: 'slice'):
      • id (string): Unique identifier for this replacement option.
      • type ('slice'): Indicates this is a slice replacement.
      • addSlice (Slice): The ProseMirror Slice object to insert as the replacement content.
      • metadata? (Record<string, any>): Optional extra metadata for this replacement option (e.g., source, category).
    • TextReplacementOption (type: 'text'):
      • id (string): Unique identifier for this replacement option.
      • type ('text'): Indicates this is a text replacement.
      • addText (string): The plain text to insert as the replacement content.
      • metadata? (Record<string, any>): Optional extra metadata for this replacement option (e.g., source, category).
  • displayOptions? (DisplayOptions): Optional display options to control how the suggestion is rendered in the editor UI.
    • showAsDiff? (boolean): Show alternative content as a diff widget. Default: true.
    • diffPosition? ('before' | 'after'): Where to display the diff relative to the suggestion. Default: 'before'
    • attributes? (Record<string, any>): Attributes added to rendered elements
    • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): Custom rendering function. Defaults to a function renders the suggestion as a diff.
  • metadata? (Record<string, any>): Optional extra metadata for the suggestion. This can be used to store additional information such as the source, category, or any custom data. It is not used internally by the extension but can help customize UI rendering.

getSuggestions

Returns all current suggestions.

Returns (Suggestion[])

  • Suggestion[]: The list of active suggestions.

Example 

// Get all active suggestions
const suggestions = toolkit.getSuggestions()

setSuggestions / addSuggestions

Replace or append suggestions.

Parameters

  • inputs (SuggestionsFormat[]): A list of suggestions in one of the following formats:
    • suggestions: A list of direct suggestions
    • compareDocuments: Suggestions will be generated from comparing the current document with another document

If two generated suggestions have overlapping ranges, only the first suggestion in the list will be displayed. The second suggestion will be ignored. Suggestions cannot have overlapping ranges because of a limitation in ProseMirror's decoration rendering engine.

suggestions format

  • type (string): 'suggestions'
  • suggestions (Suggestion[]): A list of direct suggestions

compareDocuments format

  • type (string): 'compareDocuments'
  • doc (Node): The document to compare against
  • displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Customize rendering
    • showAsDiff? (boolean): Show alternative content as a diff widget. Default: true.
    • diffPosition? ('before' | 'after'): Where to display the diff relative to the suggestion. Default: 'before'
    • attributes? (Record<string, any>): Attributes added to rendered elements
    • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): Custom rendering function. Defaults to a function renders the suggestion as a diff.
  • metadata? (Record<string, any>): Extra metadata for the suggestions, that can be used to store additional information about them (e.g. their source or category). It is not used internally by the AI Toolkit extension but it may help developers customize how a suggestion is displayed in the UI.

Schema issue

The doc parameter must have the same schema as the current document. If doc comes from a different editor, convert it to the target editor schema: doc: Node.fromJSON(editor.state.schema, otherEditor.getJSON())

Returns

void

Example 

// Set direct suggestions
toolkit.setSuggestions([{ type: 'suggestions', suggestions: [] }])

applySuggestion

Applies a specific suggestion.

Parameters

  • suggestionId (string): The suggestion to apply
  • options? (ApplySuggestionOptions): Options for the applySuggestion method
    • replacementOptionId? (string): The ID of the replacement option to apply. If not provided, the first replacement option will be applied

Returns

void

Example 

// Apply a suggestion by id
toolkit.applySuggestion('suggestion-1')

applyAllSuggestions

Applies all active suggestions to the document at once.

This method applies all suggestions by replacing the content at each suggestion's range with the first replacement option. After applying all suggestions, the list of active suggestions is cleared.

Parameters

None

Returns

void

Example 

// Apply all suggestions at once
toolkit.applyAllSuggestions()

removeSuggestion

Removes a specific suggestion.

Parameters

  • suggestionId (string)

Returns

void

Example 

// Remove a suggestion by id
toolkit.removeSuggestion('suggestion-1')

Styling suggestions

When the default renderDecorations function is used, the following classes are applied:

  • .tiptap-ai-suggestion: Applied on the content that is covered by the suggestion range.
  • .tiptap-ai-suggestion--selected: Applied when the cursor is inside the suggestion range.
  • .tiptap-ai-suggestion-diff: Applied on the diff widget that is displayed next to the suggestion range.
  • .tiptap-ai-suggestion-diff--selected: Applied to the diff widget when the cursor is inside the suggestion range.

Use the above classes to style the suggestions, or provide a custom renderDecorations function for full control over the UI.