CommandPalette
Paleta de comandos — uma busca dentro de um diálogo que encontra e executa comandos, páginas e registros pelo nome. Agiliza quem usa o app todo dia; tudo o que está nela também precisa de um caminho visível.
Instalação
Configure o Camaleo uma vez (Instalação) e importe o que precisar. Ele renderiza no cliente.
import { CommandPalette, CommandPaletteTrigger, CommandPaletteContent, CommandPaletteInput, CommandPaletteList, CommandPaletteGroup, CommandPaletteItem, CommandPaletteEmpty, CommandPaletteFooter } from "@camaleo/react";Anatomia
O CommandPaletteContent renderiza o fundo e o dialog num portal. O foco fica na busca; as setas movem um destaque pela lista com aria-activedescendant.
command-palette-dialog <div> · role=dialog, num portal depois de command-palette-backdrop
command-palette-header <div>
command-palette-search-icon <span>
command-palette-input <input> · role=combobox
command-palette-list <div> · role=listbox, rola
command-palette-group <div> · role=group, opcional
command-palette-group-label <span>
command-palette-item <div> · role=option
command-palette-item-icon <span>
command-palette-item-text <span>
command-palette-item-shortcut <span>
command-palette-empty <div> · quando nada corresponde
command-palette-footer <div> · opcional
Exemplos
Todo exemplo é um arquivo real que você pode copiar, no estilo, modo e marca da barra acima. Todos começam fechados: abra, digite, use as setas e o Enter, depois o Esc. A paleta não filtra sozinha. Guarde a busca no estado, renderize só os comandos que correspondem e dê ao CommandPaletteList um key={query}, para as setas seguirem a nova ordem.
Acme Finanças
WEB-142Corrigir o total do checkout no celularou aperte CtrlK
Prazo 14/11/2026 · Responsável: Ana RibeiroCtrl+K e atalhos dos comandos
Aperte Ctrl+K em qualquer lugar desta página. O botão continua sendo a entrada visível, e cada comando mostra o próprio atalho para as pessoas aprenderem.
Novo site
Escolha uma página ou uma ação.Grupos: Navegação, Ações, Recentes
Títulos ajudam a percorrer uma lista longa. Um grupo sem resultados some junto com o título, e o destaque rola até ficar à vista.
Configurações da conta
Tente “recibo” ou “adicionar usuário”.Palavras-chave e sinônimos
Digite "recibo" ou "adicionar usuário". As pessoas buscam com as próprias palavras, então procure também nas palavras-chave e mostre qual delas bateu.
Café Aurora · Admin
Abra e digite “folha de pagamento”: esta loja não tem.Estado vazio
Repita o que foi buscado e sugira o que tentar. A busca continua na caixa, fácil de corrigir.
Leads e Clientes
Resultados do servidor
Digite um nome. Enquanto a requisição roda, a lista fica com aria-busy e o rodapé diz "Buscando…"; uma busca mais nova descarta a anterior.
Notas
Páginas dentro da paleta
"Mudar tema…" abre uma página de opções. O Esc ou o Backspace com a busca vazia voltam um nível antes de fechar.
Contrato do espaço para o encontro de 05/12Carla Mendes · 10:42
Contagem e resultado anunciados
A contagem do rodapé é um status educado, lido quando a digitação pausa. Depois que um comando roda, um status fora da paleta diz o que aconteceu.
Despesas de viagem de outubroR$ 1.284,50 · 12 recibos
Um comando que você não pode rodar
Deixe na lista com aria-disabled e diga por quê. As pessoas encontram, descobrem quem pode fazer, e o Enter não faz nada.
Em contexto
Estas são partes inteiras de interface que você pode copiar, no estilo que escolheu.
Busca no topo de um dashboardCommandPalette · Button · Avatar · Stat · Card
Busca de um site de documentaçãoCommandPalette · Button · Kbd · Card
Editor: Ir para arquivoCommandPalette · Tabs · Button · Card
Boas práticas
Notas fiscais
FaçaUm atalho para o que já está na página.
Emitir e exportar têm botões próprios. A paleta é o caminho mais rápido para quem já sabe o que quer.
Notas fiscais
EviteAções que só existem na paleta.
Ninguém navega por uma caixa de busca. Se "Emitir nota fiscal" não está na página, a maioria nunca encontra.
Notas fiscais
FaçaRótulos curtos que começam com um verbo.
"Enviar lembrete de pagamento" diz o que vai acontecer, e a primeira palavra é o que as pessoas digitam.
Notas fiscais
EviteSubstantivos e frases longas.
"Nota fiscal" pode abrir, emitir ou cancelar uma. Uma frase é cortada e difícil de encontrar.
Props
PropriedadeTipoPadrãoDescrição
shortcutbooleantrueEscuta Ctrl+K (⌘K no Mac) na página toda para abrir e fechar a paleta. Desligue quando a página tiver mais de uma paleta.
openboolean—Se a paleta está aberta. Use com
onOpenChange para controlar o estado.defaultOpenbooleanfalseSe ela começa aberta. Deixe desligado: a paleta abre quando as pessoas pedem.
modal"trap-focus" | booleantrue
true prende o foco e esconde a página de trás dos leitores de tela. Mantenha o padrão.onOpenChange(open, eventDetails) => void—Chamado quando ela abre ou fecha.
eventDetails.reason diz o motivo, por exemplo escape-key.CommandPaletteContent, CommandPaletteList, CommandPaletteEmpty e CommandPaletteFooter recebem as props da sua div; passe aria-label ao conteúdo e à lista. O CommandPaletteInput recebe as props de um input, incluindo value, onChange e aria-label. O CommandPaletteTrigger recebe render.
Cada comando é um CommandPaletteItem:
PropriedadeTipoPadrãoDescrição
valuestring—Vai para
data-value, para o seu filtro ou para testes. A paleta não filtra por ele.iconReactNode—Ícone no início, escondido dos leitores de tela.
shortcutReactNode—Mostrado no fim, por exemplo teclas com Kbd ou uma dica. Só exibe: ligue o atalho você mesmo.
onSelect(() => void)—Runs the command, on click or on Enter while the item is active.
disabledbooleanfalseShown but skipped by the arrow keys, and
onSelect doesn't run. Say why in the label.O onSelect executa o comando, no clique ou no Enter com o item destacado. Ele também recebe as props da sua div, como aria-disabled, aria-keyshortcuts e onMouseDown. O CommandPaletteGroup recebe label, o título visível do grupo.
Styling hooks
Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou na própria paleta.
Atributos
data-active · aria-selected="true"no comando destacado
aria-disabled="true"um comando que não pode rodar; aparece apagado
data-valuea prop value do item
data-open · data-closedno dialog e no fundo
Tokens que ele lê
Cor
--cml-accent--cml-accent-fg--cml-border-control--cml-border-subtle--cml-dialog-bg--cml-dialog-border--cml-fg--cml-fg-secondary--cml-radius-surface--cml-shadow-surface--cml-surface-raised
Forma e tamanho
--cml-border-width--cml-popover-border-width--cml-radius-control--cml-radius-popover
Tipografia e movimento
--cml-font-body--cml-font-label
Só deste componente
--cml-cmd-active-bg--cml-cmd-active-fg--cml-cmd-border--cml-cmd-footer-border--cml-cmd-header-border
/* uma lista mais alta para o buscador de arquivos */
.editor [data-slot="command-palette-list"] {
max-height: 24rem;
}Acessibilidade
Ctrl + K / ⌘ + KAbre a paleta de qualquer lugar da página e fecha quando ela está aberta. Só com a prop shortcut ligada, e não enquanto se digita em outro campo de texto, onde editores usam Ctrl+K para links.
Enter / SpaceNo gatilho, abre a paleta com o foco na busca.
↓ / ↑Move o destaque para o próximo comando ou o anterior, dando a volta nas pontas. O foco fica na busca.
EnterExecuta o comando destacado.
EscFecha a paleta e devolve o foco ao elemento que o tinha. Não limpa a busca antes.
TabFica na busca: ela é o único controle do dialog.
- O dialog é modal e precisa de um nome: passe aria-label ao CommandPaletteContent, e outro ao CommandPaletteInput, no idioma da página.
- A busca é um combobox com aria-expanded e aria-controls apontando para o listbox. O aria-activedescendant acompanha o destaque, então o leitor de tela lê cada comando conforme você se move.
- Os resultados mudam em silêncio. Coloque a contagem num role="status" dentro da paleta e, depois que um comando roda, conte o resultado num status fora dela: a paleta sumiu e o foco voltou ao gatilho.
- O Ctrl+K escuta a página toda. Deixe shortcut ligado em uma paleta só e desligue nas outras, ou um toque abre todas.
Relacionados
ComboboxBusque numa lista para escolher o valor de um campo.DialogA janela modal sobre a qual a paleta é feita.KbdMostre as teclas de um atalho ao lado de um comando.
Esta página foi útil? · Editar esta página no GitHub