Pular para o conteúdo
Formulário

Combobox

/componentes/combobox.mdmarkdown cru, para quem lê com agent em vez de olho

Busca em lista

Escolha múltipla

Lista com famílias

Nos três tamanhos

Importar
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

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<Actions | null>sem padrão
autoComplete0.4.0

Dá ao navegador uma dica para o preenchimento automático.

stringsem padrão
autoHighlight0.4.0

Se o primeiro item que bate é destacado sozinho durante a busca.

booleanfalse
defaultInputValue0.4.0

O texto inicial do campo, no modo não controlado.

stringnumberreadonly string[]sem padrão
defaultOpen0.4.0

Se o painel começa aberto.

booleanfalse
defaultValue0.4.0

O valor escolhido inicial do combobox, no modo não controlado.

ComboboxInputValue<Value, Multiple> | nullsem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
filter0.4.0

A função que compara os itens com o texto digitado.

((item: Value, query: string, itemToString?: ((item: Value) => string) | undefined) => boolean) | nullsem padrão
filteredItems0.4.0

Os itens já filtrados a mostrar na lista.

readonly Value[] | readonly Group<Value>[]sem padrão
form0.4.0

Identifica o formulário dono do campo interno.

stringsem padrão
grid0.4.0

Se os itens da lista aparecem em grade.

booleanfalse
highlightItemOnHover0.4.0

Se passar o ponteiro sobre os itens os destaca.

booleantrue
inline0.4.0

Se a lista aparece no fluxo da página, sem o painel próprio da peça.

booleanfalse
inputRef0.4.0

Uma ref para o campo oculto.

Ref<HTMLInputElement>sem padrão
inputValue0.4.0

O texto digitado no campo do combobox.

stringnumberreadonly string[]sem padrão
isItemEqualToValue0.4.0

A 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.0

Os itens a mostrar na lista.

ComboboxItemCollection<Value, Value>readonly any[]readonly Group<any>[]sem padrão
itemToStringLabel0.4.0

Quando 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.0

Quando 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.0

O número máximo de itens a mostrar na lista.

number-1
locale0.4.0

O idioma usado para comparar textos.

LocalesArgumentsem padrão
loopFocus0.4.0

Se o foco do teclado volta ao campo ao chegar no fim da lista pelas setas.

booleantrue
modal0.4.0

Se o painel aberto fica em estado modal.

booleanfalse
multiple0.4.0

Se mais de um item pode ser escolhido.

Multiplefalse
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
onInputValueChange0.4.0

Chamado quando o texto do campo muda.

((inputValue: string, eventDetails: ChangeEventDetails) => void)sem padrão
onItemHighlighted0.4.0

Chamado quando um item ganha ou perde o destaque.

((highlightedValue: Value | undefined, eventDetails: HighlightEventDetails) => void)sem padrão
onOpenChange0.4.0

Chamado quando o painel abre ou fecha.

((open: boolean, eventDetails: OpenChangeEventDetails) => void)sem padrão
onOpenChangeComplete0.4.0

Chamado depois que as animações terminam, quando o painel abre ou fecha.

((open: boolean) => void)sem padrão
onValueChange0.4.0

Chamado quando o valor escolhido do combobox muda.

((value: ComboboxOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: ChangeEventDetails) => void)sem padrão
open0.4.0

Se o painel está aberto agora.

booleansem padrão
openOnInputClick0.4.0

Se o painel abre ao clicar no campo.

booleantrue
readOnly0.4.0

Se o usuário fica impedido de escolher outra opção do painel.

booleanfalse
required0.4.0

Se o usuário precisa escolher um valor antes de enviar o formulário.

booleanfalse
size

Tamanho do campo, o mesmo vocabulario e a mesma altura do Input.

ControlSize"md"
value0.4.0

O valor escolhido do combobox.

ComboboxInputValue<Value, Multiple> | nullsem padrão
virtualized0.4.0

Se os itens estão sendo virtualizados por fora.

booleanfalse

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.md

Uma 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>
PropTipo
labels

O que o leitor de tela ouve no xis.

{ remove?: ((label: string) => string) | undefined; }
render0.4.0

Troca 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.md

A 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.

PropTipo
render0.4.0

Troca 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.md

Os 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.md

O 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.

PropTipoPadrão
align

Alinhamento no eixo do lado escolhido.

Alignsem padrão
emptyMessage0.4.0

O que aparece quando a busca nao acha nada.

ReactNode"Nada encontrado."
finalFocus0.4.0

O elemento que recebe o foco quando o painel fecha.

booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null)sem padrão
initialFocus0.4.0

O elemento que recebe o foco quando o painel abre.

booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null)sem padrão
loading

A busca no servidor ainda nao respondeu.

booleanfalse
loadingMessage

O texto da espera do `loading`.

ReactNode"Buscando…"
mobileSheet

Abaixo de 640px a lista abre como folha encostada embaixo, em largura cheia e acima do teclado, como o calendario.

booleansem padrão
render0.4.0

Troca 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
side

Lado preferido do gatilho.

Sidesem padrão
sideOffset

Distancia entre o gatilho e o painel, em pixels.

number | OffsetFunctionsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

ComboboxGroup

/combobox-group.md

Uma 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.

PropTipo
items0.4.0

Os itens a renderizar dentro deste grupo.

readonly any[]
render0.4.0

Troca 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.md

O 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.

PropTipoPadrão
classNames

Classe por parte: `wrapper`, `input`.

Partial<Record<"input" | "wrapper", string>>sem padrão
clearable0.4.0

Mostra o botao de limpar quando ha escolha.

booleantrue
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
labels

Os 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
placeholder

O texto de espera do campo vazio.

string"Selecione"
render0.4.0

Troca 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.md

Uma opção. Mostra o visto quando escolhida.

PropTipoPadrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
index0.4.0

A posição do item na lista.

numbersem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleanfalse
onClick0.4.0

Um tratador de clique opcional, chamado quando o item é escolhido.

((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)sem padrão
render0.4.0

Troca 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.0

Um valor único que identifica este item.

anynull

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

ComboboxList

/combobox-list.md

A lista. Recebe uma função que desenha cada item, e não filhos soltos: é assim que a Base UI filtra sem redesenhar tudo.

PropTipo
render0.4.0

Troca 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.md

A 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.

PropTipoPadrão
orientation

A orientação do separador.

Orientation"horizontal"
render

Troca 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.md

O 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.

PropTipo
placeholder0.5.0

O texto de espera mostrado quando nada foi escolhido.

ReactNode

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.