Ir para o conteúdo
uiify

Framework

Next.jsTanStack StartAstroVike

Estilo

CSSTailwind

Tema

Idioma

English简体中文日本語العربيةРусскийEspañolPortuguês (Brasil)

Combobox

Combobox ARIA de valor único ou múltiplo com filtragem.

Navegadores
Chrome 114+Firefox 125+Safari 17+
Nível
2
Tamanho compactado
5.18 kB
Limite de layout forçado
0 ms
Limite do axe
0
Compatível com SSR
Sim
Contrato publicado
Ambiente de teste

Experimentar

Combobox

Padrão

Maçã
Banana
Cereja
Tâmara

Múltiplo

ReactUI
React
UI
TypeScript
Acessibilidade
Sistemas de design

Aberto

Maçã
Banana
Cereja
Tâmara

Grande

API

Combobox.Root

PropTipoPadrãoDescrição
childrenReactNode—Partes de Combobox: controle, tags, input, acionador e conteúdo.
items*ComboboxItemData[]—Lista completa de opções filtradas pelo input.
defaultInputValuestring—Texto inicial no input quando seu valor não é controlado.
defaultOpenboolean—Define se a lista começa aberta quando o estado de abertura não é controlado.
defaultValuestring | readonly string[]—Valor ou valores selecionados na primeira renderização quando a seleção não é controlada.
multiplebooleanfalsePermite selecionar e remover vários valores como tags.
allowCustomValuebooleanfalsePermite que um texto digitado ausente em items se torne um valor selecionado.
addOnPastebooleantrueAdiciona vários valores delimitados a partir de texto colado no modo múltiplo.
delimitersreadonly string[][","]Caracteres que confirmam ou separam valores digitados no modo múltiplo.
maxValuesnumber—Número máximo de valores selecionáveis no modo múltiplo.
validateValue(value: string) => boolean—Rejeita um valor personalizado quando retorna false.
filterFn(items: ComboboxItemData[], inputValue: string) => ComboboxItemData[]—Substitui o filtro integrado que reduz os itens à medida que o usuário digita.
inputValuestring—Texto no input, tornando o valor digitado controlado.
onInputValueChange(value: string) => void—Chamado com o novo texto sempre que o input muda.
onOpenChange(open: boolean, details: OpenChangeDetails) => void—Chamado quando a lista abre ou fecha, com o motivo da mudança.
onValueChange((value: string) => void) | ((value: string[]) => void)—Chamado com o valor selecionado ou o array completo de valores selecionados.
openboolean—Define se a lista está aberta, tornando o estado de abertura controlado.
valuestring | readonly string[]—Valor ou valores selecionados, tornando a seleção controlada.

Combobox.Control

PropTipoPadrãoDescrição
childrenReactNode—Tags e input renderizados dentro do controle visual compartilhado.
classNamestring—Classe aplicada ao elemento de controle.
renderReactElement | ((props, state) => ReactElement)—Substitua o elemento renderizado preservando comportamento e conexões de acessibilidade.

Combobox.Tags

PropTipoPadrãoDescrição
childrenReactNode—Conteúdo adicionado após as tags removíveis geradas.
classNamestring—Classe aplicada ao contêiner das tags geradas.
renderReactElement | ((props, state) => ReactElement)—Substitua o elemento renderizado preservando comportamento e conexões de acessibilidade.

Combobox.Input

PropTipoPadrãoDescrição
classNamestring—Classe aplicada ao input de texto.
renderReactElement | ((props, state) => ReactElement)—Substitua o elemento renderizado preservando comportamento e conexões de acessibilidade.

Combobox.Trigger

PropTipoPadrãoDescrição
childrenReactNode—Conteúdo do botão que abre a lista, como um ícone.
classNamestring—Classe aplicada ao botão acionador.
renderReactElement | ((props, state) => ReactElement)—Substitua o elemento renderizado preservando comportamento e conexões de acessibilidade.

Combobox.Content

PropTipoPadrãoDescrição
align"start" | "center" | "end"—Alinhamento da lista em relação ao input ao longo do lado escolhido.
children*(filteredItems: ComboboxItemData[]) => ReactNode—Função de renderização chamada com os itens restantes após a filtragem.
classNamestring—Classe aplicada à janela flutuante da lista.
side"top" | "right" | "bottom" | "left"—Lado do input em que a lista é posicionada.

Combobox.Item

PropTipoPadrãoDescrição
classNamestring—Classe aplicada ao elemento de opção.
item*ComboboxItemData—O item renderizado por esta opção, normalmente obtido do callback de conteúdo.

Combobox.Empty

PropTipoPadrãoDescrição
childrenReactNode—Conteúdo exibido quando a filtragem não deixa nenhum item.
classNamestring—Classe aplicada ao elemento de estado vazio.

ComboboxItemData

PropTipoPadrãoDescrição
disabledboolean—Impede a seleção deste item.
label*string—Texto exibido para o item e comparado pelo filtro.
value*string—Valor informado quando o item é selecionado.

Teclado

TeclaAção
↓ / ↑Abra e percorra as opções
EnterSelecione
EscapeFeche
a–zDigite para filtrar opções

Acessibilidade

Combobox ARIA + listbox. A opção ativa é anunciada por aria-activedescendant. O conteúdo expõe o estado aberto/fechado; as opções expõem os estados destacado, desabilitado e, no modo múltiplo, selecionado. Use Empty para explicar quando nenhuma opção corresponde. A animação de presença de Popup é desativada quando há preferência por movimento reduzido.

Pontos de integração de estilos

data-statedata-highlighteddata-disableddata-selected