Tiptap Docs

AI Suggestion extension configuration options

The AI Suggestion extension for Tiptap accepts different settings to configure the global behavior of the extension and the commands.

Rules

An array of rules to be applied during proofreading. Each rule contains

  • A unique id
  • The prompt property, a text that will be read by the AI model to generate suggestions
  • Parameters that decide how the rule is displayed in the UI, like title, color and backgroundColor

You can change the rules at any time without having to reload the editor, by using the setAiSuggestionRules command

AiSuggestion.configure({
  rules: [
    {
      id: '1',
      title: 'Spell Check',
      prompt: 'Identify and correct any spelling mistakes',
      color: '#DC143C',
      backgroundColor: 'FFE6E6',
    },
  ],
})

You can learn more about rules in this guide: Define rules

Initial Suggestions

An array of initial suggestions to display before any proofreading is done. This can be used as a performance optimization to avoid waiting for the first suggestions to be generated.

export const suggestions: Suggestion[] = [
  {
    id: '1',
    deleteRange: { from: 1, to: 5 },
    deleteText: 'Mistaek',
    replacementOptions: [
      {
        id: '1',
        addText: 'Mistake',
      },
    ],
    rule: {
      id: '1',
      title: 'Spell Check',
      prompt: 'Identify and correct any spelling mistakes',
      color: '#DC143C',
      backgroundColor: 'FFE6E6',
    },
    isRejected: false,
  },
]

AiSuggestion.configure({
  initialSuggestions: suggestions,
})

To learn more about the data that a suggestion object should contain, check the API reference.

Custom Suggestion Styles

The getCustomSuggestionDecoration function allows you to control the appearance of suggestions and provide visual cues to the user. You can add custom CSS classes to the suggestions, and add custom elements before and after them. Useful for adding popovers, tooltips, or icons to suggestions.

The custom styles and elements are implemented with the Prosemirror Decorations API.

To learn how to show a popover when you select a suggestion, follow this guide.

AiSuggestion.configure({
  getCustomSuggestionDecoration({ suggestion, isSelected, getDefaultDecorations }) {
    // You can combine the default decorations of the AI Suggestion extension with your custom ones
    const decorations = getDefaultDecorations()

    // Add a custom element before the suggestion text
    Decoration.widget(suggestion.deleteRange.from, () => {
      const element = document.createElement('span')
      element.textContent = '⚠️'
      return element
    })
    return decorations
  },
})

Customize When to Load Suggestions

By default, the AI Suggestion extension will automatically load suggestions when the editor is ready. You can disable this behavior with the loadOnStart option

AiSuggestion.configure({
  loadOnStart: false,
})

By default, the AI Suggestion extension will reload suggestions when the editor's content changes. You can disable this behavior with the reloadOnUpdate option.

AiSuggestion.configure({
  reloadOnUpdate: false,
})

You can learn to configure when to load suggestions in this guide.

Customize the Debounce Timeout

By default, the AI Suggestion extension will wait 800ms after the user stops typing to reload suggestions. This prevents the API from being called too frequently. You can configure this timeout with the debounceTimeout option.

AiSuggestion.configure({
  debounceTimeout: 1000,
})

Handle Errors When Loading Suggestions

You can provide a callback for handling errors when loading suggestions. This allows you to log errors, display error messages to the user, or take other actions when an error occurs.

A complete guide on how to handle loading and error states in the UI can be found here:

AiSuggestion.configure({
  onLoadSuggestionsError(error) {
    console.error('An error occurred while loading suggestions', error)
  },
})

Tiptap Content AI Cloud Options

If you do not provide your own backend, the AI Suggestion extension will use the Tiptap Content AI cloud to generate suggestions.

You can configure the OpenAI model to use for generating suggestions with the model option. The default model is gpt-4o-mini. We recommend it for most use cases, as it provides a good balance between speed, cost and accuracy.

AiSuggestion.configure({
  // Your Tiptap Content AI app id
  appId: 'APP_ID_HERE',
  // This needs to be your generated JWT and MUST NOT be the OpenAI API key!
  token: 'YOUR_TOKEN',
  // The model to use for generating suggestions. Defaults to "gpt-4o-mini"
  model: 'gpt-4o',
})

We currently support these OpenAI models:

  • gpt-4.1
  • gpt-4.1-2025-04-14
  • gpt-4.1-mini
  • gpt-4.1-mini-2025-04-14
  • gpt-4.1-nano
  • gpt-4.1-nano-2025-04-14
  • chatgpt-4o-latest
  • gpt-4o-mini
  • gpt-4o-mini-2024-07-18
  • gpt-4o
  • gpt-4o-2024-11-20
  • gpt-4o-2024-08-06
  • gpt-4o-2024-05-13
  • gpt-4-turbo
  • gpt-4-turbo-2024-04-09
  • gpt-4-turbo-preview
  • gpt-4
  • gpt-4-0125-preview
  • gpt-4-1106-preview
  • gpt-4-0613
  • gpt-4-0314
  • gpt-4-32k
  • gpt-4-32k-0613
  • gpt-3.5-turbo-0125
  • gpt-3.5-turbo
  • gpt-3.5-turbo-1106
  • gpt-3.5-turbo-16k

Integrate Your Own Backend and LLMs

If you want to use your own backend and LLMs to generate suggestions, you can provide a custom resolver function. This function should return an array of suggestions based on the editor's content and rules.

You will find a more comprehensive guide on how to integrate your own backend and LLMs in this guide.

AiSuggestion.configure({
  resolver: async ({ content, rules }) => {
    // Your custom logic to generate suggestions
    return suggestions
  },
})

Provide Extra Context to the LLM

If you want to provide extra information to the LLM, you can use the context option. This option allows you to pass additional data which can be used to improve the quality of the suggestions.

The context option is a string that will be added to the LLM as part of the prompt. It will be applied to all rules.

AiSuggestion.configure({
  context: 'The tone should be formal and professional.',
})

You can learn more about providing context in this guide.

Configure Caching

The AI Suggestion extension caches suggestions to minimize API calls. It splits the editor content into chunks and stores the generated suggestions for each chunk. When reloading suggestions, only modified chunks are re-fetched. This behavior is enabled by default, but you can customize it.

You can disable the cache by setting enableCache to false. This will make the AI Suggestion extension call the API for all chunks when the editor content changes.

AiSuggestion.configure({
  // Disable caching
  enableCache: false,
})

You can configure the chunk size with the chunkSize option. This option controls how many top-level nodes of the document are included in each chunk. The default value is 2, meaning that, for a document with 10 paragraphs, the AI Suggestion will create 5 chunks of 2 paragraphs each.

AiSuggestion.configure({
  // Each chunk will contain 3 top-level HTML nodes
  chunkSize: 3,
})

You can customize chunk generation by overriding the chunkHtml function. This function receives the editor content and should return an array of HTML strings, each representing a chunk. This gives you fine-grained control over how the content is split into chunks.

AiSuggestion.configure({
  chunkHtml: customChunkHtmlFunction,
})