Command
ProA searchable list of commands and destinations that opens in a dialog, usually from Cmd+K, and is driven from the keyboard while focus stays in the search field.
Playground
Press Cmd+K or Ctrl+K inside this card, or click Search.
Pages
Actions
Settings
Installation
Command comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
Command,
CommandDialog,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandItemRow,
CommandItemRowProps,
CommandList,
CommandRow,
CommandRowProps,
CommandSeparator,
} from "@wunderui/react"Then use it:
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command"
export function Pages() {
return (
<Command className="w-full max-w-md border border-border">
<CommandInput autoFocus={false} placeholder="Search or jump to..." />
<CommandList>
<CommandEmpty>No results found.</CommandEmpty>
<CommandGroup heading="Pages">
<CommandItem value="Dashboard" onSelect={() => console.log("Dashboard")}>
Dashboard
</CommandItem>
<CommandItem value="Projects" onSelect={() => console.log("Projects")}>
Projects
</CommandItem>
</CommandGroup>
</CommandList>
</Command>
)
}Expected result: You see a bordered box with a search field and a Pages group with two rows, Dashboard highlighted. Type pro and only Projects stays; Enter logs Projects.
When to use
Use Command for
- A palette that jumps to pages and runs actions from the keyboard, opened with Cmd+K or Ctrl+K
- A long list that people narrow by typing, such as people, projects or files
- A list of mixed things in groups, each with an icon and a shortcut
Use something else for
- Dropdown Menu for a short list of actions that a button opens
- Combobox for choosing one value for a form field from a list
- Autocomplete for a text field that suggests completions as people type
- Select for a plain choice between a few values on every device
Items
An item is a button with any content: a label, an icon before it, a shortcut after it. Push the shortcut to the right and show its keys as Kbd badges.
Pages
Actions
Settings
Pages
Actions
Settings
Pages
Actions
Settings
Groups
Put each CommandGroup directly in the list and its items in the group. A heading names a group, a CommandSeparator draws a hairline, and a group with no match hides itself.
Pages
Actions
Settings
Pages
Actions
Settings
States
Type to filter: items that do not match disappear and the first match becomes active. With no match the list shows CommandEmpty, and while commands load, render only a CommandEmpty with your message.
Pages
Actions
Settings
Pages
Actions
Settings
Pages
Actions
Settings
Loading commands...
List length
The list grows with its items up to 20 rem, then scrolls. The arrow keys keep working past the visible rows.
Everything
Everything
Placement
Command sits inline in a page, for a list you pick from in place. CommandDialog puts it in a modal you open yourself, and inline you should turn off autofocus on the field.
Pages
Actions
Settings
Press Cmd+K or Ctrl+K inside this card, or click Search.
Row with icon and shortcut
CommandRow is the finished row of a command menu: a 28 px icon tile, the label, optional context after it, and the shortcut as key caps or a chevron. It stands on its own and takes id, role and aria attributes, so a hand-built list can point aria-activedescendant at it. Inside Command use CommandItem, which takes its active state from the list. CommandRow replaces CommandItemRow.
Row
Keyboard interactions
Focus stays in the search field. The arrow keys move a highlight over the options instead of focusing them.
- ArrowDown
- Makes the next visible option active. After the last option it goes back to the first. The list scrolls to keep the active option in view.
- ArrowUp
- Makes the previous visible option active. Before the first option it goes to the last one.
- Enter
- Runs the active option: is called, as for a click. Close the palette in it yourself.
- Escape
- In a : closes it, and focus goes back to where it was before it opened. An inline has no Escape handler.
- TaborShift+Tab
- Leaves the field. In a focus stays inside the window; a list that is tall enough to scroll can take focus as a scroll container in Chromium.
Home, End, Page Up and Page Down are not handled, so they move the caret in the field. Cmd+K or Ctrl+K is not built in: open the palette with your own key listener.
Behavior and motion
How the palette handles the search text, the active option, groups, loading, assistive technology and motion.
- Filtering
- The list keeps items whose value contains the typed text, in any case and anywhere in the value. It never looks at the visible content, and the search text is not exposed.
- Active option
- The first option is active at the start. Arrow keys and the pointer share one highlight, and typing keeps the active option if it still matches, otherwise the first match.
- Running
- Enter and a click both run the option's select handler. Nothing closes or clears by itself, so in a dialog close it in that handler.
- Groups
- A group hides with its heading when none of its items match. A separator hides too when no visible group is on both sides of it.
- Empty
- The empty message replaces the groups when nothing matches. It doubles as a loading message: render no groups and an empty message with a spinner while commands load.
- Length
- The list is at most 20 rem tall and scrolls inside itself. The keys scroll only as far as the active option needs, and the page stays still.
- No disabled or async states
- Items cannot be disabled and the typed text is not available, so the palette cannot search a server. Leave out items that do not apply and render fetched results yourself.
- Dialog
- The dialog is modal and focuses the search field when it opens. The page behind it is inert, and a click outside or Escape closes it.
- Assistive technology
- The input is a combobox that points at the list and announces the active option. The list is a listbox named Suggestions by default, and each option reports whether it is selected.
- Focus
- While the field has keyboard focus, a thin indigo line shows along the bottom of the search row. Options never take focus, so the active one shows by its fill alone.
- Motion
- Nothing moves. The dialog opens and closes without animation because people open a palette many times a day, and the active fill changes at once.
- Reduced motion
- Nothing to reduce: no part of the palette animates, with or without the preference.
Anatomy
The figure shows an inline palette with two groups and a separator. The dialog and the empty message are not numbered: the dialog wraps the root, the message replaces the groups.
Pages
Actions
- 1
The root: a div with a 12 px radius on the popover fill that holds the search text and the active option and filters its items as the user types. Render it inline in a page or inside CommandDialog.
- 2
The search row: a magnifier and a combobox input, 40 px tall, with a hairline under it. Focus stays in this field while arrow keys move the active option, and it focuses itself on mount.
- 3
The list, up to 20 rem tall and then scrolling, that holds the groups with 4 px padding. It shows the empty state when nothing matches, and groups must be its direct children.
- 4Optional
A labelled set of items with an optional heading. It hides itself when none of its items match, and items must be its direct children.
- 5data-slot="command-item"
One option in the list. Its value is what the search matches and the arrow keys visit; Enter or a click runs it, and the active option gets the page fill.
- data-slot="command-item-actions"
- 6Optional
A thin line between two groups. While the list is filtered it hides when no visible group sits on both sides, so it never ends up first, last or doubled.
- Optional
The message shown when nothing matches, No results found by default. Pass your own children, for example a loading message.
- Optional
A ready-made palette: Command inside a Dialog up to 448 px wide, with no close button or open motion. You control the open state and the title, and wiring a shortcut is your job.
- data-slot="command-row"Optional
The finished row of a command menu: a 28 px icon tile, the label, optional context after it and the shortcut as key caps or a chevron. It stands on its own and takes the attributes of a button, so a hand-built list can point at it. It replaces CommandItemRow.
- Optional
Best practices
- Do
Give every item a unique value made of the words people search for, such as Invite member. Filtering matches the value, not the visible content, and an item without one is skipped.
- Do
Put groups directly inside the list and items directly inside the groups. A wrapper div or fragment hides items from the filter and the keyboard.
- Do
Open the dialog with a global shortcut such as Cmd+K or Ctrl+K and add a visible trigger that shows it. It opens without animation on purpose, so it never slows people down.
- Do
Show a shortcut as Kbd badges at the end of the row. They are only a hint, so register the keys yourself.
- Do
Add an aria-label to the search field when the placeholder is just an example. Otherwise the placeholder becomes its accessible name.
- Don’t
Don't use Command to search a server: it only filters the items you render and never hands you the typed text. Render results from a search that lives elsewhere.
- Don’t
Don't put a separator before the first group or after the last. One between two groups is enough, and it hides itself while filtering when it would stand alone.
- Do
Put secondary row actions (Copy link) in CommandItem actions, never inside the row's button; give the list its height with CommandList className.
API reference
Each part is a plain component, so these tables list every prop. CommandRow also takes the attributes of a button, such as id, role, aria-selected and disabled.
The root: a div with a 12 px radius on the popover fill that holds the search text and the active option and filters its items as the user types. Render it inline in a page or inside CommandDialog.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | — | Extra classes for the root, for example for an inline palette. The root has a 12 px radius so that its 8 px items stay concentric with their 4 px padding. |
| children required | ReactNode | — | The input and the list. The root keeps the search text and the active option for everything inside it. |
| numberShortcuts | boolean | false | 1–9 pick the first nine visible items while the field is empty, ⌘ or Ctrl + 1–9 while typing. Show the numbers yourself (a in the row) so people can see them. |
| tabToActions | boolean | true | Tab from the field moves into the actions of the active row (see ). Set false when Tab does something of your own. Default true. |
A ready-made palette: Command inside a Dialog up to 448 px wide, with no close button or open motion. You control the open state and the title, and wiring a shortcut is your job.
| Prop | Type | Default | Description |
|---|---|---|---|
| open required | boolean | — | Whether the window is open. Required: the dialog is controlled. |
| onOpenChange required | (open) => void | — | Called with the next open state when Escape or a click outside asks to close the window. Call it with in the of an item as well. |
| title | string | "Command palette" | The accessible name of the window, read by screen readers and not shown. by default; name what it searches, for example . |
| description | string | — | An optional accessible description of the window, visually hidden. |
| children required | ReactNode | — | The input and the list, placed inside a . |
The search row: a magnifier and a combobox input, 40 px tall, with a hairline under it. Focus stays in this field while arrow keys move the active option, and it focuses itself on mount.
| Prop | Type | Default | Description |
|---|---|---|---|
| placeholder | string | "Type a command or search..." | The hint in the empty field. by default. It is also the accessible name unless you pass . |
| autoFocus | boolean | true | Focuses the field on mount. On by default, right inside a dialog. Pass for a palette that sits in a page. |
| aria-label | string | — | The accessible name of the field. Defaults to the placeholder. |
The list, up to 20 rem tall and then scrolling, that holds the groups with 4 px padding. It shows the empty state when nothing matches, and groups must be its direct children.
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | "Suggestions" | The accessible name of the list, by default. |
| children required | ReactNode | — | The groups and , as direct children. The list reads only these to filter and to order the keys. |
A labelled set of items with an optional heading. It hides itself when none of its items match, and items must be its direct children.
| Prop | Type | Default | Description |
|---|---|---|---|
| heading | string | — | The label of the group in small tertiary text. Without it the group has no label and no heading. |
| children required | ReactNode | — | The s of the group, as direct children. |
One option in the list. Its value is what the search matches and the arrow keys visit; Enter or a click runs it, and the active option gets the page fill.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | What the search matches and what the arrow keys visit. Make it unique and put the searchable words in it. Without a value the item is skipped by the keys and hidden once someone types. |
| onSelect | () => void | — | Called on a click and on Enter while the item is active. Run the action and close the dialog here. |
| className | string | — | Extra classes for the row, for example the classes of a different layout. |
| children required | ReactNode | — | The content of the row: a label, an icon before it, a shortcut after it with . |
| actions | ReactNode | — | Secondary actions of the row (icon buttons, e.g. "Copy link"), beside it, not inside it: shown on the active or hovered row and always on touch screens. From the field, Tab moves into them, ← → between them, Shift + Tab or Escape back. Giv… |
| actionsLabel | string | — | Read after the row by screen readers, e.g. "Copy link"; tells them Tab reaches the actions. |
The message shown when nothing matches, No results found by default. Pass your own children, for example a loading message.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | "No results found." | The message drawn when no item matches. by default. |
The finished row of a command menu: a 28 px icon tile, the label, optional context after it and the shortcut as key caps or a chevron. It stands on its own and takes the attributes of a button, so a hand-built list can point at it. It replaces CommandItemRow.
| Prop | Type | Default | Description |
|---|---|---|---|
| icon required | ReactNode | — | The icon in the tile before the label. Required. |
| label required | ReactNode | — | The name of the action. Required. |
| meta | ReactNode | — | Secondary text after the label, such as the project or workspace the action belongs to. |
| keys | string[] | — | The shortcut as key caps, one string each. Leave it out and the row ends in a chevron. |
| active | boolean | — | Marks the highlighted row with the subtle fill and . Visual only: set yourself when the rows are options of a listbox. |
| onSelect | () => void | — | Called when the row is pressed or chosen with Enter or Space. |
| className | string | — | Extra classes on the row. |
| Prop | Type | Default | Description |
|---|---|---|---|
| icon required | ReactNode | — | |
| label required | ReactNode | — | |
| active | boolean | — | Marks the highlighted row (data-active, bg-subtle). Visual only: set yourself for a listbox. |
| keys | string[] | — | Shortcut keys → rendered as key caps. Omit to show a chevron instead. |
| meta | ReactNode | — | Secondary label after the title (Figma "Project"). |
| onSelect | () => void | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("command")The full library index for assistants is at /llms.txt.
Related components
Commands
/summarizeSummarize the open thread/explainExplain the selected code/testWrite tests for the open file/translateTranslate the last reply/docsSearch the WunderUI docs↑↓ to move · ↵ to run · esc to close
AI & Agents4 stylesProSlash Command MenuThe popover that opens when someone types / in the prompt: commands with a short description, filtered as they type.