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.replacementOptions
(ReplacementOption[]
): One or more possible replacements for the selected range. The user can choose which option to apply. EachReplacementOption
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 ProseMirrorSlice
object to insert as the replacement content.metadata?
(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?
(any
): Optional extra metadata for this replacement option (e.g., source, category).
- SliceReplacementOption (
metadata?
(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.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 elementsrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): Custom rendering function. Defaults to a function renders the suggestion as a diff.
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 suggestionscompareDocuments
: 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 againstdisplayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize renderingshowAsDiff?
(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 elementsrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): Custom rendering function. Defaults to a function renders the suggestion as a diff.
Returns
void
Example
// Set direct suggestions
toolkit.setSuggestions([{ type: 'suggestions', suggestions: [] }])
applySuggestion
Applies a specific suggestion.
Parameters
suggestionId
(string
): The suggestion to applyoptions?
(ApplySuggestionOptions
): Options for theapplySuggestion
methodreplacementOptionId?
(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.