Slash Command Menu
ProThe popover that opens when someone types / at the start of the prompt: commands with a short description, filtered as they type and driven by keyboard while focus stays in the field.
Playground
Commands
↑↓ to move · ↵ to run · esc to close
Nothing has run yet.
Installation
Slash Command Menu comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
SlashCommandMenu,
SlashCommand,
SlashCommandGroup,
} from "@wunderui/react"Then use it:
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 for
- Mention Picker for references to files, people, channels and links after an at sign
- Prompt Suggestion for ready-made prompts the reader clicks instead of types
- Dropdown Menu for a menu that a button opens and that takes focus itself
- Combobox for a field whose value is picked from a list
Content
A row is an icon tile, the name with its slash and a description. Leave the icon out and the row starts with the name; a long description wraps and the row grows.
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Active row
One row is filled. The same marker follows the arrow keys and the pointer, so you control which row is active.
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
List length
The panel has no height limit of its own, so a long list grows with its rows. Give it a maximum height and it scrolls inside the panel.
Commands
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Groups and keyboard
groups puts the commands under headings. useMenuKeys returns inputProps (aria-expanded, aria-controls, aria-activedescendant) for the text field when you give it the menu's id.
Groups and combobox attributes
Writing
Code
↑↓ to move · ↵ to run · esc to close
Commands
↑↓ to move · ↵ to run · esc to close
Keyboard interactions
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.
- 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 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 , 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 and motion
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
The figure marks a menu with three commands, the first active. A search with no match replaces the rows with the empty message and drops the key hint.
Commands
↑↓ to move · ↵ to run · esc to close
- 1
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.
- 2
Commands, or Commands matching /t while a query is set, in 12 px medium text. It is presentational and not one of the options.
- 3
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.
- Optional
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.
- Optional
No command matches /zz in 14 px tertiary text, shown instead of the rows when the filter finds nothing. The heading stays.
- 4Optional
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
- 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.
- Do
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.
- 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.
- Do
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.
- Do
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
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
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 is a plain component, so the table lists every prop.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| commands | SlashCommand[] | [] | The commands, in the order they are shown: . may start with a slash or not; the menu shows it with one. is the effect in one line; is a Lucide icon element, drawn at 16 px in a tile. |
| query | string | "" | The text typed after the slash, for example . Filters by name prefix, ignoring case and a leading slash. Default , which shows every command. |
| activeIndex | number | 0 | The index of the active row in the filtered list. Default . Drive it from . An index past the end marks no row. |
| onActiveIndexChange | (index) => void | — | Called with the row index when the pointer enters a row. Pass the setter of the hook () so hover and keys share one marker. |
| onSelect | (command) => 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 as well. |
| id | string | — | 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. |
| className | string | — | Extra classes for the panel, for example for a long list or a different width. |
| groups | SlashCommandGroup[] | — | Commands under headings instead of one flat list. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("slash-command-menu")The full library index for assistants is at /llms.txt.