MentionList
A list of people or other mentionables for an editor to show at the caret while typing a mention.
Overview
MentionList is the suggestion list behind an @ mention. Your editor detects the trigger, filters the items and positions the list at the caret. MentionList renders the options, highlights the typed query in each label and handles the keys.
Focus stays in the editor while the list is open. The editor forwards key presses to handleRef.current.onKeyDown, which matches the onKeyDown of Tiptap's suggestion utility: ↑/↓ move, Enter or Tab select, Esc closes.
Import
import { MentionList } from '@unflowio/ui/components/MentionList';Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | MentionItem[] | — | Required. The suggestions, already filtered |
onSelect | (item: MentionItem) => void | — | Required. Called with the chosen item, on Enter, Tab or click |
query | string | — | The text typed after the trigger. Its first match in each label is highlighted |
onClose | () => void | — | Called on Escape |
loading | boolean | — | Shows a loading status instead of the items |
emptyLabel | ReactNode | 'No matches' | Shown when there are no items |
label | string | 'Suggestions' | Accessible name of the list |
handleRef | Ref<MentionListHandle> | — | Receives the keyboard handle for the editor integration |
Default strings are translated.
MentionItem
| Field | Type | Description |
|---|---|---|
id | string | Required. Stable id |
label | string | Required. Name shown and matched against query |
sublabel | string | Second line, e.g. team or role |
avatar | string | ReactNode | An image URL for Avatar, or a node (e.g. an icon for non-person mentionables) |
MentionListHandle
| Method | Type | Description |
|---|---|---|
onKeyDown | (event: KeyboardEvent | React.KeyboardEvent) => boolean | Handles a key press from the editor. Returns true when the list used the key, so the editor can skip its default |
Basic usage
<MentionList items={people} query="a" onSelect={(person) => insertMention(person)} />With an editor
Forward key presses from the editor and stop its default when the list used the key. The preview uses a plain Input: type @ and a name, then use the arrow keys and Enter.
const handleRef = useRef<MentionListHandle>(null);
<MentionList
items={matches}
query={query}
onSelect={insertMention}
onClose={closeSuggestions}
handleRef={handleRef}
/>
<Input
name="message"
label="Message"
value={text}
onChange={(event) => setText(event.target.value)}
onKeyDown={(event) => {
if (suggestionsOpen && handleRef.current?.onKeyDown(event)) {
event.preventDefault();
}
}}
/>Tiptap
With Tiptap's Mention extension, render MentionList from the suggestion's render callbacks and return handleRef.current?.onKeyDown(props.event) ?? false from onKeyDown. Pass props.items, props.query and props.command (as onSelect) through to the list.
Loading and empty
Loading…
No matches
<MentionList items={[]} loading onSelect={insertMention} />
<MentionList items={[]} query="zed" onSelect={insertMention} />Accessibility
- Renders a listbox named by
label, with the active option marked as selected. Focus stays in the editor, as screen readers expect for comboboxes. - The active option resets to the first one whenever the results change.
- Loading and empty states are announced as a status.