Pular para o conteúdo
Formulário

Autocomplete

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

Busca com texto livre

Importar
import { Autocomplete } from '@rivocode/ui'

Quando usar

Campo que sugere enquanto se digita, e aceita o que não está na lista.

O painel é o mesmo do Combobox. Use ComboboxContent, ComboboxList e ComboboxItem dentro dele; só o campo troca, para AutocompleteInput.

O AutocompleteInput vazio espera com "Buscar", e não com o "Selecione" do Combobox, porque aqui o texto livre vale. O placeholder passado vence.

<Autocomplete items={CIDADES}>
  <AutocompleteInput placeholder="Cidade" />
  <ComboboxContent emptyMessage="Nenhuma cidade com esse nome.">
    <ComboboxList>
      {(cidade: string) => (
        <ComboboxItem key={cidade} value={cidade}>
          {cidade}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Autocomplete>

size mora na raiz, como no Combobox: sm, md (padrão) e lg, com a altura e o recuo do Input. Num formulário com os dois lado a lado, os dois campos ficam do mesmo tamanho.

O xis de limpar existe, mas nasce desligado: aqui o texto é o valor, e apagar tudo de uma vez raramente é o que a pessoa quer. Ligue com clearable num campo de busca, onde recomeçar é comum. O className veste a moldura, e classNames alcança wrapper e input, como no ComboboxInput.

<Autocomplete items={CIDADES} size="sm">
  <AutocompleteInput aria-label="Cidade" clearable />
</Autocomplete>

Com sugestões vindas do servidor, loading no ComboboxContent troca o vazio por "Buscando…" enquanto a resposta não chega.

Quando não usar

Quando o valor tem que ser uma das opções (o paciente da consulta, a conta do plano, a unidade de medida), use Combobox. É essa a diferença entre os dois: lá a lista manda, aqui a sugestão ajuda e o texto livre vale. Deixar passar "Marina Tolledo" num campo que devia apontar para um cadastro é um erro que só aparece no relatório do mês seguinte.

No React Native

Traduz, e o que o Autocomplete tem de próprio veio junto: o value é o texto digitado, e o que não está na lista vale. No nativo ele é controlado (value e onValueChange obrigatórios) e as sugestões entram por items na raiz, em texto, rasas ou em grupos { label, items } - no lugar do AutocompleteInput com o painel do Combobox por filho. O label é obrigatório: é o nome que o leitor de tela anuncia e o título da folha.

O campo abre numa folha de baixo, com o texto no alto e as sugestões logo abaixo, e não numa lista presa ao campo. É o teclado que decide isso: aberto, ele cobre a metade de baixo da tela, e a lista de um campo no pé do formulário nasceria escondida. A folha sobe junto com ele, como a do Combobox. Cada tecla chega ao onValueChange, tocar numa sugestão preenche o texto e fecha, e Concluir fecha com o que foi digitado. A contagem de sugestões é anunciada a cada mudança, como a região viva do web. Não há completar inline: não existe mode.

API

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<AutocompleteRootActions | null>sem padrão
autoHighlight0.4.0

Se o primeiro item que bate é destacado sozinho.

"always" | booleanfalse
defaultOpen0.4.0

Se o painel começa aberto.

booleanfalse
defaultValue0.4.0

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

stringnumberreadonly string[]sem 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
items0.4.0

Os itens a mostrar na lista.

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

Quando o valor dos itens é objeto (`<Autocomplete.Item value={object}>`), converte o objeto no texto mostrado no campo e enviado com o formulário.

((itemValue: Value) => string)sem padrão
keepHighlight0.4.0

Se o item destacado continua destacado quando o ponteiro sai da lista.

booleanfalse
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
mode0.4.0

Como o autocompletar filtra a lista e completa o texto no próprio campo.

"both""inline""list""none""list"
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem 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: AutocompleteRootOpenChangeEventDetails) => 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 texto do campo do autocompletar muda.

((value: string, eventDetails: AutocompleteRootChangeEventDetails) => 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.

booleanfalse
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 e do Combobox.

ControlSize"md"
submitOnItemClick0.4.0

Se clicar num item envia o formulário do autocompletar.

booleanfalse
value0.4.0

O texto do campo do autocompletar.

stringnumberreadonly string[]sem padrão
virtualized0.4.0

Se os itens estão sendo virtualizados por fora.

booleanfalse

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