# Command

A paleta de comandos: um campo, uma lista e o teclado.

Ela existe para quem trabalha o dia inteiro na mesma tela e já sabe para onde
quer ir. Navegar por menu custa três cliques e a memória de onde a opção mora;
aqui custa o nome da coisa.

```tsx
<Command
  open={aberta}
  onOpenChange={setAberta}
  groups={[
    { label: 'Ir para', items: [{ id: 'notas', label: 'Notas fiscais', onSelect: irParaNotas }] },
  ]}
/>
```

## A busca

Ignora acento e caixa, e lê também as `keywords` do item. "nf", "fatura" e
"boleto" levando a Notas fiscais é o que separa uma paleta útil de uma que só
acha quem já sabe o nome exato, que é justamente quem menos precisa dela.

Cada abertura começa limpa. Paleta que guarda a busca da vez passada abre
mostrando o resultado de outra pergunta.

Buscar e não achar nada também precisa ser dito. A contagem de resultados e a
mensagem de vazio saem numa região `role="status"` fora da lista: sem ela,
digitar uma busca sem resultado produz silêncio, com o foco parado no campo e
nenhuma pista de que a lista esvaziou. O `title` é o nome do campo e o da
lista, e é ele que o leitor de tela anuncia ao abrir: o `placeholder` some ao
digitar e não serve de rótulo.

## O atalho

`Ctrl+K`, ou `Cmd+K` no Mac, registrado por ela mesma. Passe `shortcut={null}`
para registrar na sua aplicação, ou outra letra para trocar.

## A lista é dado, não filho

Os itens vêm por `groups`, e não como componentes aninhados. A filtragem, a
ordem em que a seta anda e o `aria-activedescendant` moram todos num lugar só; a
forma composta obrigaria a peça a adivinhar o texto de cada filho para poder
filtrar por ele.

## Quando não usar

Menos de dez destinos não justificam. Com essa quantidade a barra lateral mostra
tudo de uma vez, e a paleta vira um passo a mais para chegar no mesmo lugar.

## No React Native

Não porta. A paleta de comandos é um gesto de mesa (abre por atalho, anda por seta, confirma por Enter), e nenhuma das três coisas existe no toque. No celular a porta equivalente é a tela de busca do router, com o campo no topo e o resultado levando direto para a tela.

## Importação

```tsx
import { Command } from '@rivocode/ui'
```

## Exemplos

### Paleta de comandos

```tsx
import { Button, Command, Kbd, type CommandGroup } from '@rivocode/ui'
import { FileText, Plus, Settings, Users } from 'lucide-react'
import { useState } from 'react'

const GROUPS: CommandGroup[] = [
  {
    label: 'Ir para',
    items: [
      {
        id: 'invoices',
        label: 'Notas fiscais',
        keywords: 'nf fatura boleto',
        icon: <FileText size={16} />,
        onSelect: () => {},
      },
      {
        id: 'customers',
        label: 'Clientes',
        keywords: 'cadastro',
        icon: <Users size={16} />,
        onSelect: () => {},
      },
      {
        id: 'settings',
        label: 'Preferências',
        icon: <Settings size={16} />,
        onSelect: () => {},
      },
    ],
  },
  {
    label: 'Criar',
    items: [
      {
        id: 'new-invoice',
        label: 'Nova nota fiscal',
        description: 'Abre o formulário em branco',
        icon: <Plus size={16} />,
        shortcut: 'mod+n',
        onSelect: () => {},
      },
    ],
  },
]

export function Palette() {
  const [open, setOpen] = useState(false)

  return (
    <div className="flex flex-col items-center gap-3">
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Buscar comando
        <Kbd size="sm" keys="mod+k" />
      </Button>
      <p className="text-sm text-fg-subtle">Ou aperte o atalho, de qualquer lugar da tela.</p>

      <Command open={open} onOpenChange={setOpen} groups={GROUPS} />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `groups` | `CommandGroup[]` | sim | 0.4.0 |  |
| `onOpenChange` | `(open: boolean) => void` | sim | 0.4.0 |  |
| `open` | `boolean` | sim | 0.4.0 |  |
| `emptyMessage` | `string` |  | 0.4.0 | Texto de quando a busca nao acha nada. |
| `placeholder` | `string` |  | 0.4.0 |  |
| `shortcut` | `string \| null` |  | 0.4.0 | Atalho que abre, combinado com Ctrl ou Cmd. |
| `title` | `string` |  | 0.4.0 | Titulo lido pelo leitor de tela. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Breadcrumb](/componentes/breadcrumb.md)
- [Menu](/componentes/menu.md)
- [Menubar](/componentes/menubar.md)
- [NavigationMenu](/componentes/navigation-menu.md)
- [Pagination](/componentes/pagination.md)
- [Sidebar](/componentes/sidebar.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)