UnflowUI
Components

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

PropTypeDefaultDescription
itemsMentionItem[]—Required. The suggestions, already filtered
onSelect(item: MentionItem) => void—Required. Called with the chosen item, on Enter, Tab or click
querystring—The text typed after the trigger. Its first match in each label is highlighted
onClose() => void—Called on Escape
loadingboolean—Shows a loading status instead of the items
emptyLabelReactNode'No matches'Shown when there are no items
labelstring'Suggestions'Accessible name of the list
handleRefRef<MentionListHandle>—Receives the keyboard handle for the editor integration

Default strings are translated.

MentionItem

FieldTypeDescription
idstringRequired. Stable id
labelstringRequired. Name shown and matched against query
sublabelstringSecond line, e.g. team or role
avatarstring | ReactNodeAn image URL for Avatar, or a node (e.g. an icon for non-person mentionables)

MentionListHandle

MethodTypeDescription
onKeyDown(event: KeyboardEvent | React.KeyboardEvent) => booleanHandles a key press from the editor. Returns true when the list used the key, so the editor can skip its default

Basic usage

Ana CostaMarketing
Bruno ReisLegal
Carla DiasBrand team
Diogo LimaEngineering
<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.