# Mention Picker

The @ picker for adding context to a prompt: files, people and channels in groups.

- Category: AI & Agents
- Page: https://wunderui.com/components/mention-picker
- Tier: Core and Pro

## Install

Mention Picker ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

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

- [Slash Command Menu](https://wunderui.com/components/slash-command-menu) for commands that start with a slash
- [Context Pill](https://wunderui.com/components/context-pill) for the chip that stays in the prompt after a pick
- [Combobox](https://wunderui.com/components/combobox) for a field whose value is picked from a list
- [Autocomplete](https://wunderui.com/components/autocomplete) for a text field that suggests values while you type

## Keyboard

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.

| Key | Action |
|---|---|
| `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 `onEnter` with its index in the flat list. With no match the key is not taken. |
| `Shift+Enter` | Not handled. It adds a line break in the prompt as usual. |
| `Escape` | Calls `onEscape`, 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

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

- `MentionPicker`: 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.
- `Group`: A group named by its heading. A group whose items are all filtered out is not drawn.
- `Group heading`: The group heading in 12 px medium tertiary text. It is presentational, so the group name is read once.
- `Mention row`: 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.
- `Leading mark`: 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.
- `Empty message`: 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

### When to use

- Use Mention Picker for @ references to people, files, channels and links. Commands that start with / use Slash Command Menu; the chip that stays after a pick is a Context Pill.

### 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.
- 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.
- 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.
- 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.
- 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.
- 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 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

| Prop | Type | Default | Description |
|---|---|---|---|
| groups* | MentionGroup[] |  | The groups in the order they are shown: `{ heading, items }`. An item is `{ id, label, kind, description?, initials?, color? }` with `kind` one of `person`, `file`, `channel` or `link`. `id` must be unique across all groups and safe in a DOM id. |
| activeId | string |  | The id of the active item. Default: the first visible item. An id that the filter removed marks no row. Drive it from `useMenuKeys` with the flat list. |
| className | string |  | Extra classes for the panel, for example `max-h-72 overflow-y-auto` for a long list or a different width. |
| emptyText | React.ReactNode |  | Text when nothing matches. Default: Nothing matches “@query”. |
| id | string |  | The id of the listbox. The options get `${id}-${item.id}`, so the field can point `aria-activedescendant` at the active one. Without it the options get ids from React that you cannot predict. |
| label | string | "Mention" | Accessible name of the list. Default "Mention". |
| onActiveIdChange | (id: string) => 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 `keys.setIndex`, so hover and keys share one marker. |
| onSelect | (item: MentionItem) => 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 `onEnter` as well. |
| query | string | "" | The text typed after the `@`, for example `n`. Keeps the items whose label contains it, ignoring case. Default `""`, which shows every item. |
| ref | React.Ref<HTMLDivElement> |  | The listbox element, e.g. to measure or scroll it. |

## Examples

### Groups: people, files, channels and links, mixed

### Row: with description, label only, long text

### Active item: first match, chosen item, item not in the list

### In the prompt box

## In context

### Mention people and files: a pick becomes a pill

Type @ after a space, narrow the list by typing, move with the arrow keys and press Enter, or click a row. The pick becomes a Context Pill above the field and is not offered again.

### Searching files: loading, results, no files, error

The picker has no loading or error state. The host shows placeholder rows while searching and a message with Try again on failure; pick a state under the card to see each.

## For AI agents

`get_component("mention-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
