npm / @tiptap/suggestion

@tiptap/suggestion

What changed in @tiptap/suggestion 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-26.

2 breaking7 new APIs and options1 behavior and defaults2 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@tiptap/suggestion 310 changes

Adds a configuration option for dismissing managed suggestion popups when a click occurs outside both the popup and editor; enabled by default for popups mounted via props.mount.
3.27.0release notes
Adds initialItems as part of async suggestion lifecycle handling.
3.27.0release notes
Adds a loading state as part of async suggestion lifecycle handling.
3.27.0release notes
Adds a minQueryLength filter as part of async suggestion lifecycle handling.
3.27.0release notes
Adds props.mount(element) to mount and automatically position a popup, returning an unmount function; manual positioning remains supported.
3.27.0release notes
Exposes placement, offset, flip, container, and resolved floatingUi configuration so consumers can drive their own positioning loop.
3.27.0release notes
Adds a callback to filter when suggestions are displayed, useful in collaborative environments to prevent suggestions from opening for remote users.
3.15.1release notes

Supports debounced asynchronous suggestion items and aborts in-flight requests.
3.27.0release notes

Fixes peer dependency resolution conflicts when installing dependencies after package updates.
3.22.4release notes
Suggestions dismissed via Escape no longer reappear while the user keeps typing in the same word; they return after whitespace, a newline, or moving the cursor to a different trigger.
3.22.0release notes

Install this required dependency for the Floating UI replacement affecting @tiptap/suggestion.
2.0.0upgrade guide
Suggestion replaces Tippy.js with Floating UI for floating elements, so integrations relying on Tippy.js need to migrate.
2.0.0upgrade guide