UI

Combobox

Campo de texto com lista filtrada enquanto o usuário digita (autocomplete).

Digite para filtrar.

Instalação

npx shadcn@latest add @lenstech/combobox

Uso

import { ComboBox, ComboBoxContent, ComboBoxInput, ComboBoxItem } from "@/components/ui/combobox"
<ComboBox name="cidade" label="Cidade">
  <ComboBoxInput placeholder="Buscar cidade…" />
  <ComboBoxContent>
    <ComboBoxItem id="cwb">Curitiba — PR</ComboBoxItem>
    <ComboBoxItem id="sp">São Paulo — SP</ComboBoxItem>
  </ComboBoxContent>
</ComboBox>

O filtro já vem pronto (contém, sem diferenciar maiúsculas/acentos conforme o idioma) e a lista mostra "Nenhum resultado encontrado." quando nada combina.

Dois valores: o item escolhido e o texto digitado

value / onChange guardam o id do item selecionado; inputValue / onInputChange guardam o texto do campo. Normalmente você só precisa do primeiro. No formulário, name envia o id (use formValue="text" para enviar o texto). As props selectedKey / onSelectionChange estão obsoletas no React Aria.

Exemplos

Com seções e abrindo ao focar

menuTrigger="focus" abre a lista assim que o campo recebe foco — bom para listas curtas.

Aceita valor livre

Com allowsCustomValue, o usuário pode digitar algo que não está na lista.

Não encontrou? Digite o nome do bairro.

Controlado com conteúdo rico

Se o item tiver mais que texto, informe textValue — é ele que aparece no campo e é usado no filtro.

Nenhum cliente selecionado.

Obrigatório

Desabilitado

Quando usar

  • Use para listas longas (cidades, clientes, produtos) ou quando o usuário já sabe o que procura.
  • Não use com poucas opções — use Select ou Radio Group.
  • Não use para busca livre que leva a uma página de resultados — use Search Field.

API

ComboBox

Aceita todas as props do ComboBox do React Aria, mais:

Prop

Type

ComboBoxInput

Aceita as props do Input do React Aria (placeholder…), mais groupClassName (classes da caixa externa com o botão de abrir).

ComboBoxContent

Aceita as props do ListBox (items…), mais:

Prop

Type

ComboBoxItem e ComboBoxSection

O mesmo que ListBoxItem e ListBoxSection.

On this page