Troubleshooting

Suggestions do not open

Check that the trigger begins a word, composition has ended, and the host is editable with a collapsed selection. A bare hook must spread getInputProps() onto its textarea. A custom editor must call setEditor() and refresh().

An empty successful result still opens the popup; add Mention.Empty to explain that state.

A selection does not commit

Commit rejects obsolete results and changed selections. Move the caret to the intended query or type again. A custom adapter should report the current text and caret together and apply replacements using the same offset units.

Controlled values do not update

Use value and onChange on Mention.Input. For hooks, pass them into getInputProps({ value, onChange }). Do not overwrite the returned handlers or ref afterward.

Async results disappear while typing

Old results are intentionally removed as soon as a query changes. Display Mention.Loading while waiting. Keep the fetcher reference stable unless its behavior changes. Forward the abort signal to network requests to avoid unnecessary work; the library also rejects late results when the fetcher ignores cancellation.

Caret positioning drifts

The built-in textarea mirror measures browser text layout. Font loading, transformed ancestors, and CSS zoom can change that geometry. Reproduce without those factors first. A rich editor adapter should use its editor's viewport caret measurement.

Accessibility checker reports a scrolling list

Mention uses the focused textbox to navigate suggestions and scroll the highlighted option into view. Axe can report scrollable-region-focusable because its heuristic recognizes combobox-controlled popups but not textbox-controlled ones. Check arrow-key access to every option and preserve the host's focus. See Accessibility for the recorded findings and manual verification limits.

Popup is clipped or outside the desired reading order

The default popup portals into the host document's body. Set container to an appropriate application container, or container={null} to render in place. Test the resulting layout and reading order with the assistive technologies your application supports.

Undo differs between hosts

Rich editor history belongs to its transaction system. The textarea adapter uses the browser's insertion command to preserve native history where supported. WebKit can group the preceding typing and mention into one undo step; Chromium and Firefox separate them in the tested flow. Its value-setter fallback still notifies React but cannot guarantee a native undo entry.

Reporting a problem

Include a minimal example, React and browser versions, the host type, and exact typing/selection steps. For rich editors, include the adapter and document schema.