Capítulo 54 de 108

Command

Core Idea

Menu de comando para busca e ações rápidas (padrão "command palette" tipo VS Code/Spotlight). Built on cmdk (não Base UI), diferente da maioria dos componentes deste lote.

Key Concepts

  • CommandInput: campo de busca com filtro fuzzy embutido do cmdk.
  • CommandList: container rolável dos resultados.
  • CommandEmpty: mensagem exibida quando a busca não retorna nada.
  • CommandGroup: agrupa itens com heading (título da seção, ex. heading="Suggestions").
  • CommandSeparator: divisor entre grupos.
  • CommandShortcut: hint de atalho alinhado à direita, mesma convenção visual dos menus.
  • CommandDialog: envolve Command num Dialog/overlay, controlado (open/onOpenChange), para o padrão "command palette" acionado por botão ou atalho global.

Code Examples

<Command className="max-w-sm rounded-lg border">
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>
        <Calendar />
        <span>Calendar</span>
      </CommandItem>
      <CommandItem disabled>
        <Calculator />
        <span>Calculator</span>
      </CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Settings">
      <CommandItem>
        <User />
        <span>Profile</span>
        <CommandShortcut>⌘P</CommandShortcut>
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
  • O que demonstra: uso standalone (sem dialog) do Command, com dois grupos, ícone+texto em CommandItem, e shortcut no último item.
const [open, setOpen] = React.useState(false)

<Button onClick={() => setOpen(true)} variant="outline">Open Menu</Button>
<CommandDialog open={open} onOpenChange={setOpen}>
  <Command>
    <CommandInput placeholder="Type a command or search..." />
    <CommandList>
      <CommandEmpty>No results found.</CommandEmpty>
      <CommandGroup heading="Suggestions">
        <CommandItem>Calendar</CommandItem>
      </CommandGroup>
    </CommandList>
  </Command>
</CommandDialog>
  • O que demonstra: padrão "command palette" completo, Command embrulhado em CommandDialog controlado por estado externo.

Reference Tables

Composição:

Command
├── CommandInput
└── CommandList
    ├── CommandEmpty
    ├── CommandGroup
    │   ├── CommandItem
    │   └── CommandItem
    ├── CommandSeparator
    └── CommandGroup
        ├── CommandItem
        └── CommandItem

Key Takeaways

  1. Diferente de quase todos os outros componentes deste lote, Command é baseado em cmdk (npm install cmdk), não @base-ui/react.
  2. CommandDialog é o padrão recomendado para transformar o Command num overlay tipo command palette, controlado via open/onOpenChange.
  3. CommandGroup heading="..." é a forma de dar título a uma seção de resultados (não existe CommandLabel separado como nos menus).
  4. CommandEmpty é essencial para dar feedback quando a busca não encontra nada.
  5. CommandItem disabled desabilita seleção/filtro daquele item específico.

Connects To

  • Dialog: CommandDialog reaproveita a mecânica de overlay do Dialog para o padrão command palette.
  • Dropdown Menu: visualmente similar (grupos, shortcuts, ícones), mas Command é focado em busca/filtro por texto, não navegação por hover/clique de menu.
AnteriorMenubarPróximoAlert