Command

A command palette for searching and executing actions — think ⌘K. Provides a searchable list of commands grouped by category, with built-in keyboard navigation. Often rendered inside a Dialog for a floating Cmd+K experience. Built on cmdk.

Anatomy

<Command> is the root container (handles filtering logic). CommandInput is the search field. CommandList is the scrollable results area. CommandEmpty renders when no results match. CommandGroup labels a section of items. CommandItem is a selectable action. CommandSeparator draws a horizontal divider between groups. CommandShortcut shows a keyboard hint aligned right.

CommandInput (filtered search)CommandGroup (labeled section)CommandEmpty (no results state)

Examples

Multi-group with shortcuts

Tools palette

Design Guidelines

Do

  • Group items by category. Use CommandGroup with a meaningful heading — categories help users scan and understand the scope of available commands.
  • Always provide a no-results state. CommandEmpty must be present so users know their search returned nothing rather than thinking the palette is broken.
  • Pair with a Dialog for ⌘K. Wrap the Command in a CommandDialog or a regular Dialog — the floating palette pattern is the most recognized UX for command menus.

Don't

  • Don't embed without a trigger. A Command palette sitting inline on a page is unusual — users expect to open it via keyboard shortcut (⌘K) or a visible button.
  • Don't overload with hundreds of items. The palette is most useful when the item list is well-curated. Use fuzzy filtering to surface relevant results rather than listing everything.
  • Don't skip icons for complex lists. When many items have similar labels, icons provide a quick visual anchor that speeds up scanning.

Developer Reference

Accessibility & Behavior

  • CommandInput filters items automatically — the list re-renders as the user types.
  • Arrow keys navigate between CommandItem entries. Entertriggers the selected item's onSelect callback.
  • Each CommandItem accepts an onSelect prop for the action to run and a value prop that the search filter compares against.
  • CommandDialog is a pre-built wrapper that combines Command with a Dialog for the floating ⌘K pattern.
  • Items not matching the current search query are hidden automatically — no manual filtering needed.

Usage

import {
  Command,
  CommandInput,
  CommandList,
  CommandEmpty,
  CommandGroup,
  CommandItem,
  CommandSeparator,
  CommandShortcut,
  CommandDialog,
} from "@/components/ui/command"

// Inline palette
<Command className="rounded-lg border shadow-sm">
  <CommandInput placeholder="Search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Navigation">
      <CommandItem onSelect={() => router.push("/docs")}>
        Docs
        <CommandShortcut>⌘D</CommandShortcut>
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Actions">
      <CommandItem onSelect={() => setTheme("dark")}>
        Toggle Dark Mode
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

// Floating ⌘K dialog
const [open, setOpen] = useState(false)
useEffect(() => {
  const down = (e: KeyboardEvent) => {
    if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
      e.preventDefault()
      setOpen((prev) => !prev)
    }
  }
  document.addEventListener("keydown", down)
  return () => document.removeEventListener("keydown", down)
}, [])

<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Type a command..." />
  <CommandList>
    <CommandEmpty>No results.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>