Combobox
Busca em lista
Escolha múltipla
Lista com famílias
Nos três tamanhos
import { Combobox } from '@rivocode/ui'Quando usar
Escolha em lista longa, com busca.
Use quando a lista é grande demais para caber na cabeça de quem escolhe, ou quando ela vem do servidor.
Compõe com ComboboxInput, ComboboxContent, ComboboxList e
ComboboxItem. Lista com famílias de verdade ganha ComboboxGroup,
ComboboxGroupLabel e ComboboxSeparator entre uma família e outra, com o
items da raiz em grupos e um ComboboxCollection dentro de cada grupo: a
página do ComboboxGroup mostra a montagem.
Desabilitado ou somente leitura, o xis de limpar some: ele não teria o que
fazer. Dentro de <Field disabled>, a peça trava igual.
Com multiple, a escolha vira fichas dentro do próprio campo: ComboboxChips
em volta, ComboboxValue para saber o que está escolhido e um ComboboxChip
por escolha.
size mora na raiz, com o vocabulário do Input: sm, md (padrão) e lg,
com a mesma altura, o mesmo recuo e o mesmo corpo de texto. O ComboboxInput
de dentro veste o tamanho sozinho.
<Combobox items={CLIENTES} size="sm">
<ComboboxInput aria-label="Cliente" placeholder="Buscar cliente" />
</Combobox>
Busca no servidor
Enquanto a resposta não chega, o painel não pode dizer "Nada encontrado.":
é mentira, e a pessoa apaga o que digitou. Passe loading ao
ComboboxContent durante a consulta. O vazio sai, entra um giro com
"Buscando…" numa região viva, que o leitor de tela anuncia, e o painel fica
marcado como ocupado (aria-busy). O que já estava na lista continua
embaixo, para não piscar a cada tecla. loadingMessage troca o texto.
<Combobox items={clientes} filter={null} onInputValueChange={setBusca}>
<ComboboxInput aria-label="Cliente" placeholder="Buscar cliente" />
<ComboboxContent loading={consulta.isFetching} emptyMessage="Nenhum cliente com esse nome.">
<ComboboxList>
{(cliente: Cliente) => (
<ComboboxItem key={cliente.value} value={cliente}>
{cliente.label}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
filter={null} desliga o filtro local, porque quem filtra é o servidor. O
Autocomplete divide o mesmo painel, e o loading vale igual nele.
Quando não usar
Com cinco opções fixas, use Select: ele custa menos, não pede digitação e não
tem estado de "nada encontrado" para tratar. Busca numa lista que a pessoa
enxerga inteira só acrescenta um teclado no caminho.
Quando o que a pessoa digita também vale (uma cidade que não está na lista,
um termo de busca), use Autocomplete. Aqui a lista manda: o valor final tem
que ser uma das opções, e texto que não casa com nenhuma se perde ao sair do
campo.
E não use para navegar. Campo com busca que leva a outra tela é Command, a
paleta. O combobox devolve um valor a um formulário, e quem escolhe nele espera
que a escolha fique escrita ali, não que a página troque.
No React Native
Traduz: o @rivocode/ui-native exporta Combobox - a lista abre numa folha com busca sem acento, e a folha sobe com o teclado; items na raiz, rasa ou em grupos { label, items }, não ComboboxItem por filho; loading e loadingMessage na raiz, e a busca digitada sai por onQueryChange. A API não é a mesma do web (no nativo tudo é controlado), e a tabela de paridade diz o que muda peça a peça.
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<Actions | null> | sem padrão |
autoComplete0.4.0Dá ao navegador uma dica para o preenchimento automático. | string | sem padrão |
autoHighlight0.4.0Se o primeiro item que bate é destacado sozinho durante a busca. | boolean | false |
defaultInputValue0.4.0O texto inicial do campo, no modo não controlado. | stringnumberreadonly string[] | sem padrão |
defaultOpen0.4.0Se o painel começa aberto. | boolean | false |
defaultValue0.4.0O valor escolhido inicial do combobox, no modo não controlado. | ComboboxInputValue<Value, Multiple> | null | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
filter0.4.0A função que compara os itens com o texto digitado. | ((item: Value, query: string, itemToString?: ((item: Value) => string) | undefined) => boolean) | null | sem padrão |
filteredItems0.4.0Os itens já filtrados a mostrar na lista. | readonly Value[] | readonly Group<Value>[] | sem padrão |
form0.4.0Identifica o formulário dono do campo interno. | string | sem padrão |
grid0.4.0Se os itens da lista aparecem em grade. | boolean | false |
highlightItemOnHover0.4.0Se passar o ponteiro sobre os itens os destaca. | boolean | true |
inline0.4.0Se a lista aparece no fluxo da página, sem o painel próprio da peça. | boolean | false |
inputRef0.4.0Uma ref para o campo oculto. | Ref<HTMLInputElement> | sem padrão |
inputValue0.4.0O texto digitado no campo do combobox. | stringnumberreadonly string[] | sem padrão |
isItemEqualToValue0.4.0A comparação que decide se o valor de um item do combobox é o valor escolhido. | ((itemValue: Value, value: Value) => boolean) | sem padrão |
items0.4.0Os itens a mostrar na lista. | ComboboxItemCollection<Value, Value>readonly any[]readonly Group<any>[] | sem padrão |
itemToStringLabel0.4.0Quando o valor dos itens é objeto (`<Combobox.Item value={object}>`), converte o objeto no texto mostrado no campo. | ((itemValue: Value) => string) | sem padrão |
itemToStringValue0.4.0Quando o valor dos itens é objeto (`<Combobox.Item value={object}>`), converte o objeto no texto enviado com o formulário. | ((itemValue: Value) => string) | sem padrão |
limit0.4.0O número máximo de itens a mostrar na lista. | number | -1 |
locale0.4.0O idioma usado para comparar textos. | LocalesArgument | sem padrão |
loopFocus0.4.0Se o foco do teclado volta ao campo ao chegar no fim da lista pelas setas. | boolean | true |
modal0.4.0Se o painel aberto fica em estado modal. | boolean | false |
multiple0.4.0Se mais de um item pode ser escolhido. | Multiple | false |
name0.4.0Identifica o campo quando o formulário é enviado. | string | sem padrão |
onInputValueChange0.4.0Chamado quando o texto do campo muda. | ((inputValue: string, eventDetails: ChangeEventDetails) => void) | sem padrão |
onItemHighlighted0.4.0Chamado quando um item ganha ou perde o destaque. | ((highlightedValue: Value | undefined, eventDetails: HighlightEventDetails) => void) | sem padrão |
onOpenChange0.4.0Chamado quando o painel abre ou fecha. | ((open: boolean, eventDetails: OpenChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando o painel abre ou fecha. | ((open: boolean) => void) | sem padrão |
onValueChange0.4.0Chamado quando o valor escolhido do combobox muda. | ((value: ComboboxOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void) | sem padrão |
open0.4.0Se o painel está aberto agora. | boolean | sem padrão |
openOnInputClick0.4.0Se o painel abre ao clicar no campo. | boolean | true |
readOnly0.4.0Se o usuário fica impedido de escolher outra opção do painel. | boolean | false |
required0.4.0Se o usuário precisa escolher um valor antes de enviar o formulário. | boolean | false |
sizeTamanho do campo, o mesmo vocabulario e a mesma altura do Input. | ControlSize | "md" |
value0.4.0O valor escolhido do combobox. | ComboboxInputValue<Value, Multiple> | null | sem padrão |
virtualized0.4.0Se os itens estão sendo virtualizados por fora. | boolean | false |
Partes
Combobox se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.
ComboboxChip
/combobox-chip.mdUma escolha, com o xis de tirar.
O xis por dentro diz o que se remove. Quando a ficha é texto, o nome sai pronto
do próprio conteúdo ("Remover Design"), e quando ela não é (um
Avatar, um Badge), o aria-label da ficha é que responde. Sem um dos dois o
leitor de tela lê uma fila de "Remover, Remover, Remover", e a WCAG 2.4.6 pede
que o nome distinga.
labels.remove recebe o texto da ficha e devolve o nome, para trocar o verbo ou
traduzir:
<ComboboxChip labels={{ remove: (label) => `Tirar ${label} da seleção` }}>
Design
</ComboboxChip>
| Prop | Tipo |
|---|---|
labelsO que o leitor de tela ouve no xis. | { remove?: ((label: string) => string) | undefined; } |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxChipState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxChips
/combobox-chips.mdA moldura das fichas da escolha múltipla, com o campo de busca dentro dela.
O campo entra como último filho, e não ao lado: as fichas e a digitação são o mesmo campo aos olhos de quem usa, e separar os dois faz a busca parecer um filtro de outra coisa.
Por isso a moldura é dela: borda, altura e foco do campo ficam no
ComboboxChips, e o ComboboxInput de dentro perde a borda própria e cresce
até o fim da linha. Desabilitada, ela veste o desabilitado da casa; somente
leitura, o tracejado, e os xis das fichas somem.
Dentro dela, o clearable do ComboboxInput sai de cena: cada ficha já tem o
seu xis, e um limpar geral encostado neles é o botão errado no lugar mais fácil
de acertar sem querer.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxChipsState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxCollection
/combobox-collection.mdOs itens de um ComboboxGroup, já filtrados pela busca.
Não renderiza elemento nenhum: recebe uma função e a chama para cada item do
items do grupo em volta que casa com o que se digitou. É o que faz a lista em
grupos filtrar; a página do ComboboxGroup tem a montagem inteira.
Quando não usar
Na lista rasa, sem grupo. Ali a função vai direto no ComboboxList, que já
embrulha o que a ComboboxCollection faria.
Sem prop própria: repassa ao elemento de baixo o que você mandar.
ComboboxContent
/combobox-content.mdO painel da lista, em portal com o tema. Traz a mensagem de vazio por dentro, em emptyMessage.
side, align e sideOffset posicionam o painel, com o mesmo significado e a
mesma folga padrão de 6px do MenuContent, do SelectContent, do
PopoverContent e do TooltipContent.
No celular, abaixo de 640px, a lista vira folha encostada embaixo, em largura
cheia e logo acima do teclado, que é quem cobria o painel preso ao campo. Ela
ocupa no máximo metade da área visível e não escurece o fundo, para o campo
continuar à vista enquanto se digita. Vale também para o Autocomplete, que usa
este mesmo painel. mobileSheet={false} devolve o painel preso ao campo.
| Prop | Tipo | Padrão |
|---|---|---|
alignAlinhamento no eixo do lado escolhido. | Align | sem padrão |
emptyMessage0.4.0O que aparece quando a busca nao acha nada. | ReactNode | "Nada encontrado." |
finalFocus0.4.0O elemento que recebe o foco quando o painel fecha. | booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null) | sem padrão |
initialFocus0.4.0O elemento que recebe o foco quando o painel abre. | booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null) | sem padrão |
loadingA busca no servidor ainda nao respondeu. | boolean | false |
loadingMessageO texto da espera do `loading`. | ReactNode | "Buscando…" |
mobileSheetAbaixo de 640px a lista abre como folha encostada embaixo, em largura cheia e acima do teclado, como o calendario. | boolean | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
sideLado preferido do gatilho. | Side | sem padrão |
sideOffsetDistancia entre o gatilho e o painel, em pixels. | number | OffsetFunction | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxGroup
/combobox-group.mdUma seção da lista, com ComboboxGroupLabel de cabeçalho.
Serve para lista longa que tem famílias de verdade: clientes por cidade, produtos por categoria. Agrupar por agrupar aumenta a altura da lista sem diminuir a busca, que é justamente o que a peça existe para resolver.
Montagem
Os grupos entram pelo items da raiz, cada um com os seus itens, e a lista
desenha cada grupo por função. O grupo recebe os itens dele em items, e o
ComboboxCollection de dentro desenha só os que casam com a busca:
const ESTADOS = [
{ value: 'Paraíba', items: [{ value: 'joao-pessoa', label: 'João Pessoa' }] },
{ value: 'Pernambuco', items: [{ value: 'recife', label: 'Recife' }] },
]
<Combobox items={ESTADOS}>
<ComboboxInput aria-label="Cidade" placeholder="Buscar cidade" />
<ComboboxContent emptyMessage="Nenhuma cidade com esse nome.">
<ComboboxList>
{(estado) => (
<ComboboxGroup key={estado.value} items={estado.items}>
<ComboboxGroupLabel>{estado.value}</ComboboxGroupLabel>
<ComboboxCollection>
{(cidade) => (
<ComboboxItem key={cidade.value} value={cidade}>
{cidade.label}
</ComboboxItem>
)}
</ComboboxCollection>
</ComboboxGroup>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
Grupo cujos itens nenhum casa com a busca some inteiro, com o cabeçalho.
Quando não usar
Os itens escritos como filhos do grupo, um ComboboxItem por linha, não
filtram: a busca só alcança o que veio do items. Com filhos fixos, digitar
"zzz" mostra o "Nada encontrado" e a lista inteira embaixo dele. Para lista
curta que não precisa de busca, o grupo é do Select, com o SelectGroup.
| Prop | Tipo |
|---|---|
items0.4.0Os itens a renderizar dentro deste grupo. | readonly any[] |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxInput
/combobox-input.mdO campo de busca com o limpar e a seta encostados. Vive dentro do Combobox.
Vazio, ele espera com "Selecione". Troque por um placeholder que diga por
onde a busca procura ("Buscar cliente"), ou desligue com placeholder="".
O className veste a raiz, que aqui é a moldura que segura o campo e os dois
botões, e não o <input>. Para alcançar cada uma delas pelo nome, use
classNames com as partes wrapper e input:
<ComboboxInput classNames={{ input: "font-mono" }} />
O AutocompleteInput tem a mesma moldura e as mesmas duas partes, então
o className dos dois veste a mesma coisa.
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `wrapper`, `input`. | Partial<Record<"input" | "wrapper", string>> | sem padrão |
clearable0.4.0Mostra o botao de limpar quando ha escolha. | boolean | true |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
labelsOs textos da peca, para trocar o idioma: `clear` e o nome do xis que limpa a escolha, e `open` o da seta que abre a lista. | Partial<ComboboxInputLabels> | sem padrão |
placeholderO texto de espera do campo vazio. | string | "Selecione" |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxInputState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxItem
/combobox-item.mdUma opção. Mostra o visto quando escolhida.
| Prop | Tipo | Padrão |
|---|---|---|
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
index0.4.0A posição do item na lista. | number | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onClick0.4.0Um tratador de clique opcional, chamado quando o item é escolhido. | ((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxItemState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
value0.4.0Um valor único que identifica este item. | any | null |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxList
/combobox-list.mdA lista. Recebe uma função que desenha cada item, e não filhos soltos: é assim que a Base UI filtra sem redesenhar tudo.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxListState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxSeparator
/combobox-separator.mdA linha entre dois ComboboxGroup da lista.
É a irmã do SelectSeparator, e fecha a paridade com o MenuSeparator: as três
listas da biblioteca cortam do mesmo jeito. Como no Select, ela sai com
role="presentation": um nó com papel próprio no meio das opções quebraria o
"opção 3 de 12" que o leitor de tela anuncia.
Quando não usar
Enquanto a busca é o caminho principal, a linha decora e não orienta: quem digita três letras nunca vê o corte, porque a lista filtrada some com ele. Ela serve à lista parada, aberta e curta o bastante para ser lida de uma vez, e aí só entre grupos que têm nome.
| Prop | Tipo | Padrão |
|---|---|---|
orientationA orientação do separador. | Orientation | "horizontal" |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, ComboboxSeparatorState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
ComboboxValue
/combobox-value.mdO que está escolhido, para as fichas saberem o que desenhar.
Não renderiza elemento nenhum: recebe uma função e devolve o que ela montar. É
ela que dá ao ComboboxChips a lista do que desenhar na escolha múltipla com
ficha.
| Prop | Tipo |
|---|---|
placeholder0.5.0O texto de espera mostrado quando nada foi escolhido. | ReactNode |