Skip to content
WunderUI

Command

Pro

A 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

Installation

Command comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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

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.

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

List length

The list grows with its items up to 20 rem, then scrolls. The arrow keys keep working past the visible rows.

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

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

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

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

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

  • Optional

    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.

  • data-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"
  • Optional

    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.

PropTypeDefaultDescription
classNamestring—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 requiredReactNode—The input and the list. The root keeps the search text and the active option for everything inside it.
numberShortcutsbooleanfalse1–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.
tabToActionsbooleantrueTab 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.

PropTypeDefaultDescription
open requiredboolean—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.
titlestring"Command palette"The accessible name of the window, read by screen readers and not shown. by default; name what it searches, for example .
descriptionstring—An optional accessible description of the window, visually hidden.
children requiredReactNode—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.

PropTypeDefaultDescription
placeholderstring"Type a command or search..."The hint in the empty field. by default. It is also the accessible name unless you pass .
autoFocusbooleantrueFocuses the field on mount. On by default, right inside a dialog. Pass for a palette that sits in a page.
aria-labelstring—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.

PropTypeDefaultDescription
labelstring"Suggestions"The accessible name of the list, by default.
children requiredReactNode—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.

PropTypeDefaultDescription
headingstring—The label of the group in small tertiary text. Without it the group has no label and no heading.
children requiredReactNode—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.

PropTypeDefaultDescription
valuestring—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.
classNamestring—Extra classes for the row, for example the classes of a different layout.
children requiredReactNode—The content of the row: a label, an icon before it, a shortcut after it with .
actionsReactNode—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…
actionsLabelstring—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.

PropTypeDefaultDescription
childrenReactNode"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.

PropTypeDefaultDescription
icon requiredReactNode—The icon in the tile before the label. Required.
label requiredReactNode—The name of the action. Required.
metaReactNode—Secondary text after the label, such as the project or workspace the action belongs to.
keysstring[]—The shortcut as key caps, one string each. Leave it out and the row ends in a chevron.
activeboolean—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.
classNamestring—Extra classes on the row.

PropTypeDefaultDescription
icon requiredReactNode—
label requiredReactNode—
activeboolean—Marks the highlighted row (data-active, bg-subtle). Visual only: set yourself for a listbox.
keysstring[]—Shortcut keys → rendered as key caps. Omit to show a chevron instead.
metaReactNode—Secondary label after the title (Figma "Project").
onSelect() => void—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("command")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.