Command

Command surfaces are for fast retrieval. They help users jump to a page, trigger a known action, or recall a label they do not want to hunt through navigation for. In this system the command palette is compact, typographic, and best used for speed, not discovery.

Installation

Purchase access, then open /account/install to issue a registry token.

Usage

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

<Command>
  <CommandInput placeholder="Search docs..." />
  <CommandList>
    <CommandGroup heading="Pages">
      <CommandItem>
        Dialog
        <CommandShortcut>RET</CommandShortcut>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Why This Primitive Exists

Global navigation, dense sidebars, and long settings pages are slow when the user already knows the destination. Command surfaces reduce that friction.

• Use Command inline when the search surface belongs inside the page.
• Use CommandDialog when the command palette should temporarily sit above the current context.
• Keep results short, exact, and grouped by intent so scanning stays fast.

Examples

Inline Command Surface

The smallest useful pattern is an input followed by grouped results. Keep the first group immediately actionable.

<Command>
  <CommandInput placeholder="Search commands, pages, and collections..." />
  <CommandList>
    <CommandGroup heading="Navigate">
      <CommandItem>
        Launch calendar
        <CommandShortcut>G L</CommandShortcut>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Group Results By Intent

Separate destinations from actions. That keeps a user from confusing "go there" with "do this".

<CommandList>
  <CommandGroup heading="Views">{/* destinations */}</CommandGroup>
  <CommandSeparator />
  <CommandGroup heading="Actions">{/* commands */}</CommandGroup>
</CommandList>

In Context

Command should accelerate a workflow that already has structure around it. Let the page explain the task and use the palette for shortcuts.

<Card>
  <CardHeader>{/* task context */}</CardHeader>
  <CardContent>
    <Command>{/* quick navigation and actions */}</Command>
  </CardContent>
</Card>

Dialog Variant

Use CommandDialog when the palette should open above the page with the same visual language as the rest of the overlay system.

<CommandDialog open={open} onOpenChange={setOpen}>
  <CommandInput placeholder="Jump to a primitive..." />
  <CommandList>{/* groups and items */}</CommandList>
</CommandDialog>

Guidance

Favor Retrieval Over Exploration

• Use command when users already know the label, destination, or action they want.
• Do not use it as the only navigation model for a feature that still needs visible orientation.
• If the result labels require explanation paragraphs, the palette is carrying too much.

Keep The Result Set Tight

• Group by intent such as Views, Actions, or Recent.
• Put the most likely actions first in each group.
• Keep shortcuts supportive, not required.

Choose Inline Or Dialog Deliberately

• Use inline command inside settings panels, side rails, or admin workspaces.
• Use CommandDialog for global jumps and cross-surface actions.
• If the interaction needs forms, confirmations, or multi-step editing, move to a dialog or dedicated page instead.

API Reference

Core Exports

Notable Props

The command implementation is a Swiss wrapper around cmdk, so the underlying accessibility and keyboard behavior remain available.