# Command

A searchable command palette dialog with keyboard navigation (⌘K pattern).

- Category: Navigation & Layout
- Page: https://wunderui.com/components/command
- Tier: Core and Pro

## Install

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

## Import

```tsx
import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandItemRow, CommandItemRowProps, CommandList, CommandRow, CommandRowProps, CommandSeparator } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
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

- [Dropdown Menu](https://wunderui.com/components/dropdown-menu) for a short list of actions that a button opens
- [Combobox](https://wunderui.com/components/combobox) for choosing one value for a form field from a list
- [Autocomplete](https://wunderui.com/components/autocomplete) for a text field that suggests completions as people type
- [Select](https://wunderui.com/components/select) for a plain choice between a few values on every device

## Keyboard

Focus stays in the search field. The arrow keys move a highlight over the options instead of focusing them.

| Key | Action |
|---|---|
| `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: `onSelect` is called, as for a click. Close the palette in it yourself. |
| `Escape` | In a `CommandDialog`: closes it, and focus goes back to where it was before it opened. An inline `Command` has no Escape handler. |
| `Tab` or `Shift+Tab` | Leaves the field. In a `CommandDialog` 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

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

- `Command`: 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.
- `CommandDialog`: 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.
- `CommandInput`: 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.
- `CommandList`: 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.
- `CommandGroup`: 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.
- `CommandItem`: 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.
- `CommandSeparator`: 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.
- `CommandEmpty`: The message shown when nothing matches, No results found by default. Pass your own children, for example a loading message.
- `CommandRow`: 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 `aria-activedescendant` at it. It replaces CommandItemRow.
- `CommandItemRow`
- `Item Actions`

## Best practices

### When to use

- Use Command for a searchable list of actions and destinations opened by a shortcut. For picking a value in a form use a combobox or select, for a short fixed list a dropdown menu.

### 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.
- 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.
- 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.
- Show a shortcut as Kbd badges at the end of the row. They are only a hint, so register the keys yourself.
- Add an aria-label to the search field when the placeholder is just an example. Otherwise the placeholder becomes its accessible name.
- Put secondary row actions (Copy link) in CommandItem actions, never inside the row's button; give the list its height with CommandList className.

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

## API reference

### Command

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The input and the list. The root keeps the search text and the active option for everything inside it. |
| className | string |  | Extra classes for the root, for example `w-full max-w-md border border-border` for an inline palette. The root has a 12 px radius so that its 8 px items stay concentric with their 4 px padding. |
| 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 `Kbd` in the row) so people can see them. |
| tabToActions | boolean | true | Tab from the field moves into the actions of the active row (see `CommandItem` `actions`). Set false when Tab does something of your own. Default true. |

### CommandDialog

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The input and the list, placed inside a `Command`. |
| onOpenChange* | (open: boolean) => void |  | Called with the next open state when Escape or a click outside asks to close the window. Call it with `false` in the `onSelect` of an item as well. |
| open* | boolean |  | Whether the window is open. Required: the dialog is controlled. |
| className | string |  | Classes for the dialog box (width, e.g. `max-w-xl`). |
| description | string |  | An optional accessible description of the window, visually hidden. |
| title | string | "Command palette" | The accessible name of the window, read by screen readers and not shown. `Command palette` by default; name what it searches, for example `Search the workspace`. |

### CommandEmpty

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode | "No results found." | The message drawn when no item matches. `No results found.` by default. |

### CommandGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The `CommandItem`s of the group, as direct children. |
| heading | string |  | The label of the group in small tertiary text. Without it the group has no label and no heading. |

### CommandInput

| Prop | Type | Default | Description |
|---|---|---|---|
| aria-label | string |  | The accessible name of the field. Defaults to the placeholder. |
| autoFocus | boolean | true | Focuses the field on mount. On by default, right inside a dialog. Pass `false` for a palette that sits in a page. |
| placeholder | string | "Type a command or search..." | The hint in the empty field. `Type a command or search...` by default. It is also the accessible name unless you pass `aria-label`. |

### CommandItem

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The content of the row: a label, an icon before it, a shortcut after it with `ml-auto`. |
| actions | React.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. |
| className | string |  | Extra classes for the row, for example the classes of a different layout. |
| onSelect | () => void |  | Called on a click and on Enter while the item is active. Run the action and close the dialog here. |
| 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. |

### CommandItemRow

| Prop | Type | Default | Description |
|---|---|---|---|
| icon* | React.ReactNode |  |  |
| label* | React.ReactNode |  |  |
| active | boolean |  | Marks the highlighted row (data-active, bg-subtle). Visual only: set `aria-selected` yourself for a listbox. |
| className | string |  |  |
| keys | string[] |  | Shortcut keys → rendered as key caps. Omit to show a chevron instead. |
| meta | React.ReactNode |  | Secondary label after the title (Figma "Project"). |
| onSelect | () => void |  |  |

Also accepts React.ButtonHTMLAttributes attributes.

### CommandList

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The groups and `CommandEmpty`, as direct children. The list reads only these to filter and to order the keys. |
| className | string |  |  |
| label | string | "Suggestions" | The accessible name of the list, `Suggestions` by default. |

### CommandRow

| Prop | Type | Default | Description |
|---|---|---|---|
| icon* | React.ReactNode |  | The icon in the tile before the label. Required. |
| label* | React.ReactNode |  | The name of the action. Required. |
| active | boolean |  | Marks the highlighted row with the subtle fill and `data-active`. Visual only: set `aria-selected` yourself when the rows are options of a listbox. |
| className | string |  | Extra classes on the row. |
| keys | string[] |  | The shortcut as key caps, one string each. Leave it out and the row ends in a chevron. |
| meta | React.ReactNode |  | Secondary text after the label, such as the project or workspace the action belongs to. |
| onSelect | () => void |  | Called when the row is pressed or chosen with Enter or Space. |

Also accepts React.ButtonHTMLAttributes attributes.

### CommandSeparator

| Prop | Type | Default |
|---|---|---|


## Examples

### Items: text, icons, or icons with shortcuts

### Groups: one group, headings, or headings with separators

### States: default, filtered, no match and loading

### List length: eight entries, or thirty in a list that scrolls

### Placement: inline in a page, or in a dialog

### Row: an icon, a label, context and the shortcut

## In context

### Workspace palette: pages and actions, opened with Cmd+K

Click inside the card, then press Cmd+K or Ctrl+K, or click Search. Type, move with the arrow keys and press Enter to run, and Escape or a click outside closes it and returns focus to the button.

### Reviewer picker: an inline list with people

A small palette that sits in the page. Each row has an avatar, a name and a role, the chosen person gets a check, and the search matches the name.

### Project switcher: a list with a Create action under a separator

The projects are one group and Create project is another, split by a separator. Choosing Create adds an untitled project and makes it the current one.

### Row actions, number keys and a list height

`actions` on a CommandItem sit beside the row, never inside its button, and show on the active or hovered row. From the field, Tab moves into them, the arrow keys move between them, Shift + Tab or Escape comes back (`tabToActions={false}` keeps Tab for your own use). `numberShortcuts` lets 1–9 pick a row while the field is empty, ⌘ or Ctrl + 1–9 while typing. CommandList and CommandDialog take a `className`.

## For AI agents

`get_component("command")`

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