Command

Component Foundation and Origin

The <Command /> component provided here is built upon the excellent cmdk library, created by Paco Coursey. cmdk offers a fast, unstyled, and accessible core for command menu functionality, which we then style and integrate into this UI library.

Installation Procedure

npx shadcn@latest add command

Basic Command Component Usage

  Command, // The main wrapper component for the command menu.
  CommandDialog, // A variant that displays the command menu within a Dialog.
  CommandEmpty, // Content to display when the search yields no results.
  CommandGroup, // Used to group related CommandItems, often with a heading.
  CommandInput, // The input field for typing search queries or commands.
  CommandItem, // Represents a single selectable item within the list.
  CommandList, // The scrollable container for CommandItems and CommandGroups.
  CommandSeparator, // A visual separator between CommandGroups or CommandItems.
  CommandShortcut, // Displays keyboard shortcuts associated with a CommandItem.
} from "@/components/ui/command"; // Adjust import path as necessary.

// Basic structure of a Command menu
<Command>
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search Emoji</CommandItem>
      <CommandItem>Calculator</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Settings">
      <CommandItem>Profile</CommandItem>
      <CommandItem>Billing</CommandItem>
      <CommandItem>Settings</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

This example demonstrates the fundamental structure: a main <Command> wrapper containing an <CommandInput>, a <CommandList>, and within the list, <CommandGroup> elements to organize <CommandItem>s. <CommandEmpty> provides feedback when filtering yields no results, and <CommandSeparator> visually divides sections.

Command Component Examples

Command Menu within a Dialog

For use cases like a global command palette triggered by a keyboard shortcut (e.g., Ctrl+K or Cmd+K), the <CommandDialog /> component is ideal. It wraps the standard <Command> structure within a modal dialog, handling the open/close state and overlay behavior.

export function CommandMenu() {
  const [open, setOpen] = React.useState(false);

  React.useEffect(() => {
    const down = (e: KeyboardEvent) => {
      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen((open) => !open);
      }
    };
    document.addEventListener("keydown", down);
    return () => document.removeEventListener("keydown", down);
  }, []);

  return (
    <CommandDialog open={open} onOpenChange={setOpen}>
      <CommandInput placeholder="Type a command or search..." />
      <CommandList>
        <CommandEmpty>No results found.</CommandEmpty>
        <CommandGroup heading="Suggestions">
          <CommandItem>Calendar</CommandItem>
          <CommandItem>Search Emoji</CommandItem>
          <CommandItem>Calculator</CommandItem>
        </CommandGroup>
      </CommandList>
    </CommandDialog>
  );
}

Usage as a Combobox

The <Command /> component serves as the core engine for the Combobox component. By nesting <Command> within a <PopoverContent>, you can create powerful autocomplete and selection inputs. Refer to the Combobox documentation for detailed implementation examples of this pattern.

Component Changelog

2024-10-25 Classes for icons

Added gap-2 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 to the <CommandItem /> to automatically style icon inside.

Add the following classes to the cva call in your command.tsx file.

const CommandItem = React.forwardRef<
  React.ElementRef<typeof CommandPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>
>(({ className, ...props }, ref) => (
  <CommandPrimitive.Item
    ref={ref}
    className={cn(
      "... gap-2 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
      className,
    )}
    {...props}
  />
));