Feature Request: First-class async fetching, positioning, and UX patterns for @tiptap/suggestion

[gethari]

Description

Overview

After building a production suggestion/mention system on top of @tiptap/suggestion, we identified nine gaps between what the plugin provides and what a real-world async dropdown requires. Each gap forced us to implement workarounds inside render() — a lifecycle hook that was never designed to be a data-fetching or UI management layer.

This issue documents each gap as a distinct use case, the current workaround, and what a first-class API could look like. Addressing even a subset of these would significantly reduce the boilerplate every consumer has to write.

---

Gap 1 — items() has no cancellation mechanism (stale results on fast typing)

Problem

items() is called on every keystroke. Tiptap awaits each call and fires onUpdate for every resolution — including stale ones from superseded queries. A user typing @john fires 5 concurrent items() calls; whichever resolves last wins, regardless of whether its query is still current.

Workaround

Bypass items() entirely, return Promise.resolve([]), and manage all fetching inside render() with a hand-rolled AbortController + debounce:

{
  // items() bypassed — Tiptap provides no cancellation
  items: () => Promise.resolve([]),
  render: () => {
    let abortController: AbortController | null = null;
    const debouncedFetch = debounce(async (query, cb) => {
      abortController?.abort();
      abortController = new AbortController();
      const results = await fetch(`/api/users?q=${query}`, {
        signal: abortController.signal,
      }).then(r => r.json());
      cb(results);
    }, 300);
    return {
      onStart(props) { debouncedFetch(props.query, update); },
      onUpdate(props) { debouncedFetch(props.query, update); },
      onExit() { debouncedFetch.cancel(); abortController?.abort(); },
    };
  },
}

Proposed API

// Option A — pass AbortSignal to items()
async items({ query, signal }) {
  return fetch(`/api/users?q=${query}`, { signal }).then(r => r.json());
}

// Option B — built-in debounce option
Suggestion({ debounce: 300, async items({ query }) { ... } })

---

Gap 2 — No popup positioning

Problem

Tiptap provides clientRect (a getter for the decoration node's bounding rect) in SuggestionProps, but provides no mechanism to actually position a popup element relative to it. Every consumer must integrate their own positioning library.

Workaround

Integrate Floating UI manually inside render(), using clientRect as the virtual anchor:

onStart(props) {
  currentClientRect = props.clientRect;
  void computePosition(
    { getBoundingClientRect: () => currentClientRect?.() ?? new DOMRect() },
    popupElement,
    { strategy: 'fixed', placement: 'bottom-start', middleware: [offset(6), flip(), shift()] }
  ).then(({ x, y }) => {
    Object.assign(popupElement.style, { left: `${x}px`, top: `${y}px`, visibility: 'visible' });
  });
}

Proposed API

A placement option and a onPosition callback (or Floating UI middleware support) would let consumers skip the positioning boilerplate entirely:

Suggestion({
  placement: 'bottom-start',  // NEW — resolves position automatically from clientRect
  offset: 6,                  // NEW
})

---

Gap 3 — Popup doesn't reposition on scroll or viewport resize

Problem

Even with custom positioning wired up, the popup becomes misaligned whenever the user scrolls the page or resizes the viewport while the suggestion is open. Tiptap does not emit any event for this.

Workaround

Manually attach scroll (capture) and resize listeners inside onStart, forward them to the positioning function, and remove them in onExit:

onStart() {
  window.addEventListener('scroll', reposition, { capture: true, passive: true });
  window.addEventListener('resize', reposition, { passive: true });
},
onExit() {
  window.removeEventListener('scroll', reposition, { capture: true });
  window.removeEventListener('resize', reposition);
}

Proposed API

If the plugin owns positioning (see Gap 2), repositioning on scroll/resize would be automatic. Alternatively, a repositionOn?: string[] option listing DOM events that should trigger a reposition.

---

Gap 4 — Popup renders into document.body, breaking dialog/modal containment

Problem

Portaling the popup element into document.body places it outside any <dialog> or Radix/Headless UI modal that contains the editor. This causes z-index conflicts and (in browsers that implement the top-layer for <dialog>) the popup appears behind the dialog's backdrop.

Workaround

Walk up the DOM from props.decorationNode (or props.editor.view.dom) to find the nearest [role="dialog"] ancestor, and portal the popup inside that element instead:

onStart(props) {
  const dialogAncestor =
    props.decorationNode?.closest('[role="dialog"]') ??
    props.editor.view.dom.closest('[role="dialog"]');
  const container = dialogAncestor ?? document.body;
  container.appendChild(popupElement);
}

Proposed API

A container option accepting an HTMLElement or a resolver function:

Suggestion({
  container: (props) =>
    props.decorationNode?.closest('[role="dialog"]') ?? document.body,
})

---

Gap 5 — Escape key is intercepted by dialogs before ProseMirror sees it

Problem

handleKeyDown in the ProseMirror plugin runs at the editor's DOM level. A <dialog> element (or any overlay with keydown capture) intercepts Escape before it reaches ProseMirror, so onKeyDown is never called and the suggestion popup is never dismissed. The dialog closes instead.

Workaround

Attach a capture-phase keydown listener on document that intercepts Escape before any overlay:

onStart() {
  document.addEventListener('keydown', handleEscapeKey, { capture: true });
},
function handleEscapeKey(event: KeyboardEvent) {
  if (event.key !== 'Escape' || !isOpen) return;
  event.preventDefault();
  event.stopPropagation();
  cleanup(); // close suggestion, NOT the dialog
}

Proposed API

The plugin should attach its own capture-phase Escape listener so suggestions inside dialogs work out of the box, without consumers needing to hook into document themselves.

---

Gap 6 — No outside-click dismissal

Problem

Tiptap dismisses the suggestion when the editor loses focus (blur), but not when the user clicks on an unrelated part of the page while the editor retains focus (e.g. clicking a sidebar element scrolls the page but doesn't blur the editor). The popup stays open indefinitely.

Workaround

Attach a capture-phase pointerdown listener on document and check whether the click target is outside both the popup element and the editor:

document.addEventListener('pointerdown', (event) => {
  const isInsidePopup = popupElement.contains(event.target);
  const isInsideEditor = editor.view.dom.contains(event.target);
  if (!isInsidePopup && !isInsideEditor) {
    editor.commands.blur();
    cleanup();
  }
}, { capture: true });

Proposed API

A dismissOnOutsideClick: boolean option (defaulting to true) that handles this automatically.

---

Gap 7 — No charLimit / minimum-query-length gating

Problem

For large user directories or expensive APIs, it is not practical to fetch suggestions on a single character (e.g. @a potentially matching thousands of users). There is no built-in way to suppress the fetch until the query reaches a minimum length, or to show the user a hint like "Type at least 2 characters to search".

Workaround

Gate the items() bypass manually: check query.length < charLimit before calling the debounced fetch, and push a different UI state to the renderer component:

if (query.length < charLimit) {
  component.updateProps({ isCharLimitNotMet: true, users: [] });
  return;
}
// proceed with fetch

Proposed API

Suggestion({
  minQueryLength: 2,  // NEW — suppress items() until query reaches this length
})

When minQueryLength is set and not yet met, Tiptap should pass items: [] to onStart/onUpdate along with a new queryTooShort: true flag in SuggestionProps so renderers can show a hint.

---

Gap 8 — No pre-populated / instant-open items

Problem

A common UX pattern is to show a pre-populated list immediately when the trigger character is typed (e.g. @ opens a dropdown with recently-mentioned users before any characters are typed). This requires items to be shown before any async fetch, instantly on trigger. There is no way to distinguish onStart with an empty query from onUpdate triggered by the user typing and deleting back to empty.

Workaround

Carry a separate initialItems config value, resolve it synchronously inside onStart, and inject it before the first fetch:

onStart(props) {
  const prePopulated = getInitialItems(); // synchronous getter
  if (props.query.length === 0 && prePopulated.length > 0) {
    component.updateProps({ users: prePopulated, isOpen: true });
    return; // skip fetch
  }
  // normal fetch path
}

Proposed API

Suggestion({
  // NEW — synchronous items shown immediately on trigger, before any query is typed
  initialItems: () => getRecentlyMentionedUsers(),
})

SuggestionProps would expose an isInitial: boolean flag so renderers can differentiate between "just opened" and "user has typed".

---

Gap 9 — No loading state signal

Problem

Between the user typing a character and the items() promise resolving, there is nothing in SuggestionProps to indicate that a fetch is in progress. Renderers cannot show a spinner or skeleton without tracking this state themselves.

Workaround

Manually update the renderer component with a isLoading: true prop immediately before calling the debounced fetch, and isLoading: false in the callback:

component.updateProps({ isLoading: true }); // before fetch
debouncedFetch(query, (items) => {
  component.updateProps({ items, isLoading: false }); // after fetch
});

Proposed API

SuggestionProps should include a loading: boolean field that is true from the moment items() is called until it resolves:

interface SuggestionProps {
  // ... existing fields
  loading: boolean; // NEW — true while items() is in-flight
}

---

Summary Table

Gap	Workaround LoC	Proposed API
1. items() cancellation (stale results)	~20	AbortSignal in items() props, or debounce option
2. Popup positioning	~20	placement + offset options
3. Reposition on scroll/resize	~8	Automatic when plugin owns positioning
4. Dialog/modal portal containment	~6	container resolver option
5. Escape capture in dialogs	~10	Capture-phase listener in plugin
6. Outside-click dismissal	~10	dismissOnOutsideClick option
7. charLimit / minimum query length	~15	minQueryLength option + queryTooShort flag
8. Pre-populated / instant-open items	~15	initialItems option + isInitial flag
9. Loading state	~6	loading: boolean in SuggestionProps
Total	~110 lines

All nine of these are currently implemented by consumers in render() — a hook that was designed for UI lifecycle management, not data fetching or DOM event orchestration. First-class support for any subset would make @tiptap/suggestion significantly more self-contained for async use cases.

---

Environment

• @tiptap/suggestion: 3.20.x
• @tiptap/core: 3.x
• Framework: React (ReactRenderer)

---

Related

• Discussion #1449 — suggestions when typing fast
• suggestion.ts — items() is awaited with no cancellation

Use Case

All @/# or suggestion decorations rendered in the editor.

Type

New feature

[gethari]

@bdbch I can take up a PR for this, in-case if the team is ok in doing this

[bdbch]

Sure. I will assign you to #7730

[gethari]

Sure @bdbch , I'll work on it