Combobox
Seleção com busca, no padrão APG combobox + listbox: uma parada de Tab, setas ↑/↓, Home/End, Enter seleciona, Esc fecha e devolve o foco. Opções via `options`; aceita `id`, `name`, `aria-*` e integra com FormField.
Quando usar
Quando o usuário precisa escolher entre muitas opções e a busca por texto acelera a seleção. Útil para listas de documentos, categorias, países ou qualquer conjunto superior a uma dúzia de itens.
Quando não usar
Para poucas opções (até 5), um Select simples é mais rápido. Para valores que não existem na lista, use um campo de texto livre com Input.
Acessibilidade
- Usa role="combobox" e aria-expanded para indicar o estado aberto/fechado ao leitor de tela.
- A lista filtrada pode ser navegada com setas acima/abaixo, e Enter confirma a seleção.
- Esc fecha a lista e Tab move o foco para o próximo elemento.
- O valor selecionado é anunciado como live region para confirmar a escolha.
options é um array de objetos value + label. value é o valor controlado; onChange recebe o novo valor.
Preview
Variantes e composição
| Prop / grupo | Valores |
|---|---|
props | options · value · defaultValue · onValueChange · placeholder · searchPlaceholder · emptyText · name · id · invalid · required · disabled · labels · portalContainer |
removidas na 4.0 | onChange(value) → use onValueChange (guia docs/migracao-4.0.md; codemod codemod-4) |
deprecadas | ariaLabel (use rótulo visível ou aria-labelledby) · emptyMessage (use emptyText); anunciadas na 4.0, saem na 5.0 |