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. No código: combobox — src/components/combobox.tsx · Formulários

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 / grupoValores
propsoptions · value · defaultValue · onValueChange · placeholder · searchPlaceholder · emptyText · name · id · invalid · required · disabled · labels · portalContainer
removidas na 4.0onChange(value) → use onValueChange (guia docs/migracao-4.0.md; codemod codemod-4)
deprecadasariaLabel (use rótulo visível ou aria-labelledby) · emptyMessage (use emptyText); anunciadas na 4.0, saem na 5.0

Uso

Fonte do componente