# Slash Command Menu

The popover that opens when someone types / in the prompt: commands with a short description, filtered as they type.

- Category: AI & Agents
- Page: https://wunderui.com/components/slash-command-menu
- Tier: Core and Pro

## Install

Slash Command Menu ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { SlashCommandMenu, SlashCommand, SlashCommandGroup } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { SlashCommandMenu } from "@wunderui/react"

const commands = [
  { name: "/summarize", description: "Summarize the open thread" },
  { name: "/test", description: "Write tests for the open file" },
]

export function Commands() {
  return <SlashCommandMenu commands={commands} query="t" onSelect={(command) => console.log(command.name)} />
}
```

Expected result: You see a 320 px panel headed Commands matching /t with one row, /test, and the key hint under it, and clicking the row logs /test. Wire the key hook and a textarea to open it from a prompt.

## When to use

### Use Slash Command Menu for

- Actions that start with a slash at the beginning of a prompt: switch mode, summarize, write tests, search the docs
- A short list that the reader narrows by typing the first letters of a name
- A menu that opens under or over a text field while focus stays in the field

### Use something else

- [Mention Picker](https://wunderui.com/components/mention-picker) for references to files, people, channels and links after an at sign
- [Prompt Suggestion](https://wunderui.com/components/prompt-suggestion) for ready-made prompts the reader clicks instead of types
- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for a menu that a button opens and that takes focus itself
- [Combobox](https://wunderui.com/components/combobox) for a field whose value is picked from a list

## Keyboard

The keys belong to the prompt, not the menu. Focus stays in the textarea, and a hook handles four keys while the menu has rows.

| Key | Action |
|---|---|
| `ArrowDown` | Moves the active row down. 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` | Runs the active command: the hook calls `onEnter` with its index. With no match the key is not taken, so a composer sends the text as a message. |
| `Shift+Enter` | Not handled. It adds a line break in the prompt as usual. |
| `Escape` | Calls `onEscape`, where you close the menu. The text stays. While nothing matches the hook ignores the key, so close the empty message in your own handler. |

Home, End, Page Up, Page Down and Tab are not handled and work in the field as usual. With no match the hook handles no key, so Escape and Enter reach your own handler.

## Behavior

What the menu does with its query, active row, screen readers and motion. Opening, closing and running a command are the prompt's job.

- **Opening:** The menu has no open state, so render it while the prompt is a slash command (slash plus letters, no space). Keep a dismissed flag so Escape closes it without deleting the text.
- **Filtering:** The list keeps the commands whose name starts with the query, ignoring case and any leading slash, in the order you pass them. A name without a slash is shown with one.
- **Active row:** The active index counts in the filtered list, not in your commands, and hover reports the row too so pointer and arrow keys share one marker. An index past the end marks no row.
- **Running:** A click runs the select handler with the command, and the keyboard path goes through the key hook with an index in the same filtered list. Clear the text and close the menu in the same step.
- **No match:** The rows are replaced by No command matches /zz and the key hint is dropped. The prompt keeps working, and Enter reaches your handler and sends the text.
- **Long list:** The panel has no maximum height and does not scroll. Add a height limit through a class and scroll the active row into view yourself.
- **Loading and failure:** Commands come from the list at once. The menu has no loading or error state, so draw your own status if the list loads, and report a failing command in a status line.
- **Assistive technology:** The panel is a listbox named Commands and each row an option. While rows show, point the field at the panel and the current row, keep the textarea's own role, and say what ran in a status line.
- **Motion:** The menu does not animate itself. The page fades it in quickly, which only changes opacity.
- **Reduced motion:** With reduced motion the fade stays as the only change and nothing moves. The active row changes at once either way.

## Anatomy

- `SlashCommandMenu`: A listbox named Commands: a 320 px panel (narrower on small screens) with a 1 px border, 12 px radius, 4 px padding and a shadow. It is a plain block, and you place it above or below the prompt.
- `Heading`: Commands, or Commands matching /t while a query is set, in 12 px medium text. It is presentational and not one of the options.
- `Command row`: One option: the name with its slash in 14 px medium text and an optional 12 px description below. The active row has the subtle fill, and rows never take focus because the prompt keeps it.
- `Icon tile`: A 28 px tile with a 1 px border and an 8 px radius around your icon, drawn at 16 px, decorative and hidden from screen readers. A command without an icon has no tile.
- `Empty message`: No command matches /zz in 14 px tertiary text, shown instead of the rows when the filter finds nothing. The heading stays.
- `Key hint`: A line under a hairline reading arrows to move, enter to run, esc to close. It shows while there are rows and is not an option.

## Best practices

### When to use

- Use it for actions that start with a slash in a prompt, such as /summarize or /test. For files and people use Mention Picker, and for ready-made prompts the reader clicks use Prompt Suggestion.

### Do

- Open the menu only when the text starts with a slash and has no space yet. A slash in the middle of a sentence, a path or a URL is text, not a command.
- Pass the text after the slash as the query. The list matches names that start with it, ignores case and a leading slash, and says No command matches when none do.
- Attach the menu key hook to the textarea, point the active descendant at the current row and keep focus in the field. Rows never take focus.
- Close the menu yourself in three cases: Escape while nothing matches (the hook ignores all keys on an empty list), blur of the field, and after a run.
- Write each description as the effect of the command, like Write tests for the open file, and say in a status line what ran. A command that can fail needs its own error message.

### Don't

- Don't run a command on hover. Hover only moves the active row, and Enter or a click runs it.
- Don't let Enter send the text while the menu has rows. Call the key handler first and send only if the event was not default-prevented, or the command and the message both run.
- Don't show a long list without a height limit. Add a max height with scrolling and scroll the active row into view yourself.

## API reference

### SlashCommandMenu

| Prop | Type | Default | Description |
|---|---|---|---|
| activeIndex | number | 0 | The index of the active row in the filtered list. Default `0`. Drive it from `useMenuKeys`. An index past the end marks no row. |
| className | string |  | Extra classes for the panel, for example `max-h-72 overflow-y-auto` for a long list or a different width. |
| commands | SlashCommand[] | [] | The commands, in the order they are shown: `{ name, description?, icon? }`. `name` may start with a slash or not; the menu shows it with one. `description` is the effect in one line; `icon` is a Lucide icon element, drawn at 16 px in a tile. |
| groups | SlashCommandGroup[] |  | Commands under headings instead of one flat list. |
| id | string |  | The id of the listbox. The options get `${id}-${index}`, so the field can point `aria-activedescendant` at the active one. Without it the options get ids from React that you cannot predict. |
| onActiveIndexChange | (index: number) => void |  | Called with the row index when the pointer enters a row. Pass the setter of the hook (`keys.setIndex`) so hover and keys share one marker. |
| onSelect | (command: SlashCommand) => void |  | Called with the command object when a row is clicked. The keyboard path does not go through it: run the command from the hook's `onEnter` as well. |
| query | string | "" | The text typed after the slash, for example `t`. Filters by name prefix, ignoring case and a leading slash. Default `""`, which shows every command. |

## Examples

### Content: icon and description, no icon, no description, long text

### Active row: first, middle, last

### List length: five commands, twelve in a panel that scrolls

### Groups and combobox attributes

## In context

### Run a command: type, move, run

Type / and a letter, move with the arrow keys and press Enter to run the command, or click a row. With no match the menu says so, and Enter sends the text as a normal message.

### Long list: the panel scrolls and the active row stays in view

Twelve commands in a panel limited to 288 px. The hook only reports the index, so an effect scrolls the active row into view; ArrowUp on the first row jumps to the last.

## For AI agents

`get_component("slash-command-menu")`

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