Skip to content
WunderUI

Mention Picker

Pro

The @ picker for adding context to a prompt: people, files, channels and links in groups, filtered as you type after the at sign, and driven by keyboard while focus stays in the field.

Playground

Nora LindgrenProduct designer
Daniel OkaforFinance lead
Priya RamanEngineer
q3-report.pdfreports/2026
invoices-october.csvexports

Nothing has been picked yet.

Installation

Mention Picker comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  MentionPicker,
  MentionGroup,
  MentionItem,
  MentionKind,
} from "@wunderui/react"

Then use it:

tsx
import { MentionPicker } from "@wunderui/react"

const groups = [
  {
    heading: "People",
    items: [
      { id: "nora", label: "Nora Lindgren", kind: "person" as const, initials: "NL" },
      { id: "daniel", label: "Daniel Okafor", kind: "person" as const, initials: "DO" },
    ],
  },
]

export function Mentions() {
  return <MentionPicker groups={groups} query="n" onSelect={(item) => console.log(item.label)} />
}

Expected result: You see a 320 px panel with the heading People and two rows with avatars; Nora Lindgren is active. Clicking a row logs its label, and useMenuKeys with a textarea opens it from a prompt.

When to use

Use Mention Picker for

  • References to people, files, channels and links after an at sign in a prompt
  • A list in groups that the reader narrows by typing part of a name
  • A picker that opens over a text field while focus stays in the field

Use something else for

Groups

Each group has a heading and its own rows: people show an avatar, files, channels and links an icon tile. A group with no match disappears.

Nora LindgrenProduct designer
Daniel OkaforFinance lead
Priya RamanEngineer
Tomás FerreiraSupport
Maya KesslerOperations

Row

A row is the avatar or tile, a label and an optional description. Long text wraps and the row grows, so nothing is cut off.

Nora LindgrenProduct designer
Daniel OkaforFinance lead
Priya RamanEngineer
q3-report.pdfreports/2026
invoices-october.csvexports

Active item

One row is filled, the first match unless you set an active id. An id that is not in the list marks no row, so keep it in step with the filtered items.

Nora LindgrenProduct designer
Daniel OkaforFinance lead
Priya RamanEngineer
q3-report.pdfreports/2026

In the prompt box

PromptInput renders this list itself for its mentions prop, so the prompt and the standalone picker look the same and share the keyboard handling.

Nora LindgrenSupport lead
Daniel OkaforAccount manager
2 suggestions

Keyboard interactions

The keys belong to the prompt: focus stays in the textarea and the useMenuKeys hook handles four keys while the picker has rows. The picker has no key handlers.

ArrowDown
Moves the active row down, across group boundaries. After the last row it goes back to the first. The caret does not move.
ArrowUp
Moves the active row up. Before the first row it goes to the last one.
Enter
Picks the active item: the hook calls with its index in the flat list. With no match the key is not taken.
ShiftEnter
Not handled. It adds a line break in the prompt as usual.
Escape
Calls , where you close the picker. The text stays. While nothing matches the hook ignores the key, so close the empty message in your own handler.

The hook counts one flat list in group order, so ArrowDown goes from the last person to the first file. Home, End, Page Up, Page Down and Tab are not handled.

Behavior and motion

What the picker does with its query, groups, active row, assistive technology and motion. Opening, closing and what a pick does are the prompt's job.

Opening
The picker has no open state. Render it while the text ends in @ and a word, and keep a dismissed flag so Escape closes it without deleting text.
Filtering
Each group keeps the items whose label contains the query, anywhere and ignoring case. Empty groups are not drawn, and order is the order you pass.
Active row
The active id marks the active item, or the first visible item when there is none. An id that is not visible marks no row, and hover updates it so pointer and arrow keys share one marker.
Picking
A click calls the select handler with the item, and the keyboard path gives you an index in the flat list. Insert the mention, clear the @word and close the picker in one step.
No match
The groups give way to Nothing matches “@zz”. The prompt keeps working, and the hook handles no key until rows return.
Loading and failure
The picker has no loading or error state. Draw placeholder rows while searching and a message with retry on failure, then let the picker show rows or its empty message.
Long text and long lists
A long label or description wraps and the row grows. The panel has no maximum height and does not scroll: set a limit with a class and scroll the active row into view yourself.
Assistive technology
The panel is a listbox named Mention with named groups and option rows. Set aria-controls and aria-activedescendant on the field, and announce what was picked in a status line.
Motion
The picker does not animate. The page fades it in, which only changes opacity, and placeholder rows shimmer with the Skeleton.
Reduced motion
With reduced motion the fade is the only change and the Skeleton stops shimmering. Rows and the active marker change at once.

Anatomy

The figure marks a picker with two groups. With no match the groups give way to the empty message, and loading and error are drawn by the host.

Nora LindgrenProduct designer
Daniel OkaforFinance lead
q3-report.pdfreports/2026
  • A listbox named Mention: a 320 px panel (narrower on small screens) with a 1 px border, 12 px radius and a shadow. It is a plain block that you place above or below the prompt.

  • Optional

    A group named by its heading. A group whose items are all filtered out is not drawn.

  • Optional

    The group heading in 12 px medium tertiary text. It is presentational, so the group name is read once.

  • One option: the leading mark, the label in 14 px medium and an optional 12 px description. The active row has the subtle fill, and rows are not focusable because the prompt keeps focus.

  • A decorative mark: a 28 px avatar with initials for a person (first two letters of the label by default), or a 28 px bordered tile with an icon for a file, channel or link.

  • Optional

    The message Nothing matches “@zz” with an at-sign icon in 14 px tertiary text. It replaces the groups when the filter finds nothing.

Best practices

  • Do

    Open the picker only when @ starts a word, after a space or at the start of the text. An address like info@wunderui.com is text, not a mention.

  • Do

    Pass the text after the @ as the query. The picker keeps items whose label contains it, anywhere and ignoring case, and does not search descriptions.

  • Do

    Count the same list in the keyboard hook: flatten the groups and filter by label as the picker does. A count that does not match highlights the wrong row.

  • Do

    Give every item a unique, DOM-safe id and a kind. The id builds the option id for aria-activedescendant, and the kind picks avatar or icon.

  • Do

    Turn a pick into a Context Pill and confirm it in a status line, such as Added Nora Lindgren, 2 items of context. Don't offer items already attached.

  • Do

    Draw loading and failure yourself where the picker would be: placeholder rows while searching, a message with Try again on failure. The picker only knows rows and the empty message.

  • Don’t

    Don't leave the active id on an item the filter removed. Nothing is highlighted then, and Enter would pick an item the reader cannot see.

  • Don’t

    Don't show a long list without a height limit. The panel does not scroll by itself: add a max-height class and scroll the active row into view.

API reference

MentionPicker is a plain component, so this table lists every prop.

A listbox named Mention: a 320 px panel (narrower on small screens) with a 1 px border, 12 px radius and a shadow. It is a plain block that you place above or below the prompt.

PropTypeDefaultDescription
groups requiredMentionGroup[]—The groups in the order they are shown: . An item is with one of , , or . must be unique across all groups and safe in a DOM id.
querystring""The text typed after the , for example . Keeps the items whose label contains it, ignoring case. Default , which shows every item.
activeIdstring—The id of the active item. Default: the first visible item. An id that the filter removed marks no row. Drive it from with the flat list.
onActiveIdChange(id) => void—Called with the item id when the pointer enters a row. Map it to the index in the flat list and pass it to , so hover and keys share one marker.
onSelect(item) => void—Called with the item when a row is clicked. The keyboard path does not go through it: pick the item from the hook's as well.
idstring—The id of the listbox. The options get , so the field can point at the active one. Without it the options get ids from React that you cannot predict.
classNamestring—Extra classes for the panel, for example for a long list or a different width.
emptyTextReactNode—Text when nothing matches. Default: Nothing matches “@query”.
labelstring"Mention"Accessible name of the list. Default "Mention".
refRef<HTMLDivElement>—The listbox element, e.g. to measure or scroll it.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("mention-picker")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.