Combobox
Caixa de combinação — um campo de texto que filtra uma lista enquanto você digita. Use quando houver opções demais para rolar, ou quando a pessoa já sabe o nome do que procura.
Instalação
Configure o Camaleo uma vez (Instalação) e importe as partes que precisar, mais o ComboboxEmpty para a mensagem sem resultados. O estilo carregado cuida do campo e do popup.
import { Combobox, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem } from "@camaleo/react";Anatomia
O Combobox guarda os itens e o valor; o ComboboxInput é o campo de texto com os botões de limpar e abrir; o conteúdo é um popup renderizado num portal. Cada parte tem um data-slot que você pode usar no CSS.
Exemplos
Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.
Sem resultados
Digite um nome que não existe. O ComboboxEmpty só aparece quando nada combina, então use para dizer o que fazer, não só "Nenhum resultado".
Objetos como itens
Guarde o código, mostre o nome: itemToStringLabel preenche o campo, itemToStringValue vai para o formulário, isItemEqualToValue compara os dois.
Atribuído a: Camila Rocha
Controlado
Escolha alguém. Com value e onValueChange o resto da tela acompanha a escolha na hora.
Filtro próprio
Digite "gru" ou "galeao". Uma função filter pode buscar por código, apelido ou texto sem acento, do jeito que as pessoas digitam.
Enter escolhe o primeiro
O autoHighlight destaca o primeiro resultado enquanto você digita, então uma busca curta e Enter bastam para etiquetas.
Botões com nome
Os botões de limpar e abrir são ícones. Traduza os nomes com clearLabel e triggerLabel, e deixe-os específicos do campo.
Obrigatório, com erro
Dentro de um Field, o rótulo dá nome ao campo e o FieldError é lido junto; peça para escolher da lista, já que texto livre não vale.
Em contexto
O combobox costuma ser um campo entre vários. São pedaços inteiros de interface para copiar, no estilo que você escolheu.
Checkout expira no 3G lento
#482 · aberto em 03/11 por Rafael
Data e hora
Boas práticas
Ninguém quer rolar 27 capitais; digitar "flo" é mais rápido.
Digitar é trabalho extra quando tudo cabe na tela; use um Select ou radios.
Digite uma cidade do Brasil; entregamos em 4.812 delas.
Um rótulo, um exemplo no placeholder e uma dica do que está coberto.
Buscar o quê? Sem rótulo visível, a pessoa adivinha o escopo e o formato.
Props
Estas são as props do ComboboxInput; outros atributos de input, como placeholder, passam direto. O Combobox recebe as props da raiz do Base UI: items, value, defaultValue, onValueChange, inputValue / onInputValueChange, filter, itemToStringLabel, itemToStringValue, isItemEqualToValue, autoHighlight, limit, multiple, disabled, required e name. O ComboboxList recebe uma função de cada item; o ComboboxItem recebe value e disabled.
Styling hooks
Mude o visual sem fazer fork: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio combobox.
Atributos
Tokens que ele lê
Cor
Forma e tamanho
Tipografia e movimento
Só deste componente
Acessibilidade
- O campo tem role="combobox" com aria-expanded e aria-activedescendant, então o leitor de tela acompanha o destaque enquanto você digita.
- Dentro de um Field, o FieldLabel dá nome ao campo; fora dele, passe um aria-label.
- Os botões de limpar e abrir precisam de nome: defina clearLabel e triggerLabel no idioma da página.
- O popup vai para um portal mas mantém o estilo pelo PortalScope, e o contraste passa no WCAG 2.2 AA nos 13 estilos.