Command

Navegacao

Paleta de comandos com busca fuzzy e navegação por teclado, para localizar um ativo ou disparar uma ação sem o mouse.

ou pressione Ctrl K

Instalação

Recebe correções por update de versão. O caminho recomendado.

npm i @trdr/ui

import { Command } from "@trdr/ui/command"

Uso

import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem } from "@trdr/ui/command"

export function Exemplo() {
  return <Command />
}

Props

CommandPropsestende React.HTMLAttributes<HTMLDivElement>

Prop	Tipo	Descrição
label?	string	Rotulo acessivel deste menu de comandos. Nao aparece visualmente.
shouldFilter?	boolean	Quando `false`, desliga a filtragem/ordenacao automatica: o consumidor deve renderizar os itens validos manualmente.
filter?	(value: string, search: string, keywords?: string[]) => number	Filtro customizado: retorna um numero de 0 a 1 (1 = melhor match, 0 = escondido). Por padrao usa a biblioteca `command-score`.
value?	string	Estado controlado do item selecionado do menu.
onValueChange?	(value: string) => void	Chamado quando o item selecionado do menu muda.
loop?	boolean	Ativa o loop ao navegar com as setas ao chegar no fim ou no inicio da lista.

CommandDialogPropsestende DialogProps

Prop	Tipo	Descrição
title?	string	Titulo acessivel do dialog. Nao aparece visualmente porque o campo de busca ja comunica o proposito na tela: o titulo existe so para o Radix montar o `aria-labelledby` do dialog e para leitor de tela.
description?	string	Descricao acessivel complementar ao titulo, tambem oculta visualmente.
className?	string	Classe aplicada ao `DialogContent` que envolve o `Command`.

CommandInputPropsestende Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "type">

Prop	Tipo	Descrição
value?	string	Estado controlado do valor de busca.
onValueChange?	(search: string) => void	Chamado quando o valor de busca muda.
placeholder?	string	Texto exibido quando o campo de busca esta vazio.

CommandListPropsestende React.HTMLAttributes<HTMLDivElement>

Prop	Tipo	Descrição
label?	string	Rotulo acessivel desta lista de sugestoes. Nao aparece visualmente.

CommandEmptyPropsestende React.HTMLAttributes<HTMLDivElement>

CommandGroupPropsestende React.HTMLAttributes<HTMLDivElement>

Prop	Tipo	Descrição
heading?	React.ReactNode	Titulo exibido para este grupo de itens.
value?	string	Sem `heading`, um valor unico para o grupo passa a ser obrigatorio para filtragem/identificacao.
forceMount?	boolean	Renderiza o grupo mesmo quando a filtragem o esconderia.

CommandSeparatorPropsestende React.HTMLAttributes<HTMLDivElement>

Prop	Tipo	Descrição
alwaysRender?	boolean	Sempre renderiza este separador, mesmo quando a filtragem automatica o esconderia.

CommandItemPropsestende Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect" | "value">

Prop	Tipo	Descrição
value?	string	Valor unico do item. Se omitido, e inferido do `children` ou do texto renderizado.
keywords?	string[]	Palavras-chave adicionais usadas na filtragem.
onSelect?	(value: string) => void	Chamado quando o item e selecionado, por clique ou pela navegacao de teclado.
disabled?	boolean	Desabilita a selecao deste item.
forceMount?	boolean	Renderiza o item mesmo quando a filtragem o esconderia.

CommandShortcutPropsestende React.HTMLAttributes<HTMLSpanElement>

Quando usar

Use o Command para busca rapida sobre uma lista de acoes, ativos ou paginas, o tipo de interacao que num terminal de trading substitui "procurar no menu" por "digitar e apertar Enter". CommandDialog e a forma mais comum: um atalho de teclado (Ctrl K ou Cmd K) abre a paleta em qualquer tela, o operador digita parte do nome do ativo ou do comando, e confirma sem tirar a mao do teclado. Tambem serve fora de um modal, embutido numa pagina ou num painel lateral, sempre que a lista for longa o suficiente para exigir busca.

Quando nao usar

Para selecionar uma entre poucas opcoes visiveis (ate uns 6 a 8 itens) sem precisar filtrar, prefira Select ou RadioGroup: mais simples de operar e sem o custo de aprender que aquele campo aceita busca. Para uma unica selecao com busca dentro de um formulario convencional (nao uma paleta global de comandos), use o Combobox: ele ja empacota Popover mais Command no formato de campo de formulario, com trigger, valor e placeholder.

Anatomia

Command: a raiz. Mantem o estado de busca e da selecao ativa, e roda a navegacao por teclado (setas, Home/End, Enter) internamente via cmdk.
CommandDialog: Command dentro do Dialog proprio da biblioteca (nao o dialog embutido do cmdk), para a paleta abrir como um modal centralizado. Aceita title e description (ambos ocultos visualmente, so para acessibilidade) alem das props de Dialog (open, onOpenChange).
CommandInput (data-slot="command-input"): o campo de busca, com icone de lupa fixo. Filtra a lista a cada tecla.
CommandList (data-slot="command-list"): a area rolavel que contem grupos, itens e separadores.
CommandEmpty (data-slot="command-empty"): mensagem mostrada automaticamente quando a busca nao encontra nenhum item. So aparece quando ha zero resultados, nunca precisa de logica condicional do consumidor.
CommandGroup (data-slot="command-group"): agrupa itens sob um heading textual.
CommandItem (data-slot="command-item"): uma linha selecionavel. Aceita value (o que a busca filtra e o que onSelect recebe), keywords (termos adicionais de busca que nao aparecem na tela) e disabled.
CommandShortcut: span para o atalho de teclado no fim da linha (ex. Ctrl N), so cosmetico.
CommandSeparator (data-slot="command-separator"): linha divisoria entre grupos.

Acessibilidade

O campo de busca ganha nome acessivel atraves da prop label do Command (ou de CommandDialog, que repassa title como label): o cmdk monta um <label> oculto associado ao input via aria-labelledby, entao sempre passe algo descritivo ali (label="Buscar ativo"), nunca deixe em branco.

Navegacao por teclado: ArrowUp/ArrowDown movem a selecao (pulando itens disabled automaticamente), Enter confirma o item ativo, Escape fecha o CommandDialog (devolvendo o foco a quem abriu, como todo Dialog da biblioteca). O primeiro item elegivel fica selecionado por padrao assim que a lista monta, entao Enter sem nenhuma seta ja confirma a primeira opcao.

Cada CommandItem carrega role="option" e aria-selected/aria-disabled geridos pelo cmdk; nao adicione esses atributos a mao. O CommandDialog usa DialogTitle/DialogDescription ocultos (sr-only) para dar nome ao dialog sem repetir visualmente o que o campo de busca ja comunica.

Notas

CommandDialog compoe Dialog/DialogContent proprios da biblioteca, nao o CommandPrimitive.Dialog que o cmdk exporta: aquele monta seu proprio Radix Dialog por baixo, duplicando overlay, focus trap e a convencao de data-slot que o Dialog da TRDR ja resolve. Use sempre Command/CommandDialog importados de @trdr/ui/command, nunca cmdk diretamente: e a unica peca do design system autorizada a depender dele (CONTRACT, secao 3).

Slots e tokens

Todo elemento renderizado carrega um data-slot para estilizar partes internas sem depender de classe da biblioteca. Os tokens listados são extraídos do código fonte.

[data-slot="command"][data-slot="command-empty"][data-slot="command-group"][data-slot="command-input"][data-slot="command-input-wrapper"][data-slot="command-item"][data-slot="command-list"][data-slot="command-separator"][data-slot="command-shortcut"]

13 tokens usados

bg-border-subtlebg-popoverbg-transparentborder-bborder-border-subtleoutline-nonetext-auxtext-b3text-centertext-content-placeholdertext-content-primarytext-content-tertiarytext-popover-foreground