Command

Grouping & Organization

Use CommandGroup with descriptive heading props to organize items by category (e.g., "Suggestions", "Settings", "Recent"). Separate groups with CommandSeparator for clear visual boundaries. Limit groups to 5-8 items each to avoid overwhelming users.

Search & Filtering

The built-in fuzzy search filters items automatically. Always include a CommandEmpty component with a helpful "No results found" message. For custom filtering (e.g., async search), set shouldFilter={false} on the root Command and implement your own filter logic.

Responsive Behavior

On mobile, use the inline variant (without Dialog) since overlay command palettes are less discoverable on touch devices. When using CommandDialog, ensure the dialog content does not exceed viewport height by constraining CommandList with max-h-[300px] (the default).

Color & Contrast

The command menu uses bg-popover with text-popover-foreground for the container. Selected items highlight with bg-accent and text-accent-foreground. Group headings and shortcut text use text-muted-foreground for visual hierarchy without competing with item labels.

Keyboard Navigation

• Arrow Up / Arrow Down — Navigate between items
• Enter — Select the highlighted item
• Escape — Close the command dialog
• Cmd + K — Common shortcut to open the command palette
• Type-ahead filtering begins immediately as the user types in the search input

Screen Reader Support

• Built on cmdk which provides role="listbox" and role="option" semantics
• Group headings are announced via role="group" with aria-label
• Selected state is conveyed via aria-selected
• Disabled items are announced with aria-disabled

Focus Management

When CommandDialog opens, focus is automatically placed on the search input. Focus is trapped within the dialog overlay, preventing interaction with background content. On close, focus returns to the element that triggered the dialog. The inline Command variant does not trap focus.

Dialog Labeling

The CommandDialog accepts title and description props that render as visually hidden text (using sr-only) for screen readers. Always provide meaningful values for these props.

ARIA Attributes

{/* Command with accessible labels */}
<CommandDialog
  open={open}
  onOpenChange={setOpen}
  title="Command Palette"
  description="Search for a command to run..."
>
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Actions">
      <CommandItem onSelect={() => handleAction("profile")}>
        <User />
        <span>Profile</span>
        <CommandShortcut>⌘P</CommandShortcut>
      </CommandItem>
      <CommandItem disabled>
        <Lock />
        <span>Admin Panel</span>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</CommandDialog>