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.

Style suggestions

Learn more about how to customize the appearance of suggestions with the Style suggestions guide.

getSuggestions

Returns all current suggestions.

Returns (Suggestion[])

• Suggestion[]: The list of active suggestions.

Example

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

getSelectedSuggestion

Returns the currently selected suggestion.

A suggestion is considered "selected" when the cursor (editor.state.selection.head) is over it.

Returns (Suggestion | null)

• Suggestion | null: The currently selected suggestion, or null if no suggestion is selected.

Example

// Get the currently selected suggestion
const selectedSuggestion = toolkit.getSelectedSuggestion()

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.

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')

setHtmlSuggestions

Loads AI-powered suggestions by comparing corrected HTML with the current document content. This method is designed for integration with AI APIs that return corrected text or HTML.

This method supports two input formats:

1. Full document format: Provide the corrected document and let the toolkit compute the differences automatically
2. Changes format: Provide an array of specific text replacements (delete/insert pairs)

The method uses a diff-based approach to identify changes and creates suggestions at the appropriate document positions.

Parameters

• options (SetHtmlSuggestionsOptions): Configuration options
  • content? (string): The corrected content from your AI provider (e.g., HTML string). Use this for the full document format. Cannot be used together with changes.
  • changes? (TextChange[]): Array of text changes in the format { delete: string, insert: string }. Each change specifies text to delete and its replacement. Cannot be used together with content.
  • range? (Range): Optional range to limit suggestions to a specific portion of the document. The from value is inclusive and to is exclusive ([from, to)). Values represent absolute document positions (starting from 0 at the beginning of the document), using character offsets (not node positions). If not provided, the entire document will be processed.

Returns

SetHtmlSuggestionsResult

Returns an object containing:

• suggestions (Suggestion[]): The array of generated suggestions

Examples

Full document format with API integration

const toolkit = getAiToolkit(editor)

// Get corrected HTML from your AI API
const response = await fetch('/api/grammar-check', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ html: editor.getHTML() }),
})
const { correctedHtml } = await response.json()

// Set suggestions using the corrected HTML
const result = toolkit.setHtmlSuggestions({
  content: correctedHtml,
})

console.log(`Generated ${result.suggestions.length} suggestions`)

Full document format with range parameter

const toolkit = getAiToolkit(editor)

// Only process a specific range of the document
toolkit.setHtmlSuggestions({
  content: '<p>Corrected paragraph content</p>',
  range: { from: 0, to: 100 },
})

Changes format with single change

const toolkit = getAiToolkit(editor)

// Capitalize all occurrences of 'api' to 'API'
toolkit.setHtmlSuggestions({
  changes: [{ delete: 'api', insert: 'API' }],
})

Changes format with multiple changes

const toolkit = getAiToolkit(editor)

// Apply multiple text corrections at once
toolkit.setHtmlSuggestions({
  changes: [
    { delete: 'javascript', insert: 'JavaScript' },
    { delete: 'typescript', insert: 'TypeScript' },
    { delete: 'api', insert: 'API' },
  ],
  range: { from: 0, to: 500 },
})