Autocomplete
Busca com texto livre
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
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<AutocompleteRootActions | null> | sem padrão |
autoHighlight0.4.0Se o primeiro item que bate é destacado sozinho. | "always" | boolean | false |
defaultOpen0.4.0Se o painel começa aberto. | boolean | false |
defaultValue0.4.0O texto inicial do autocompletar, no modo não controlado. | stringnumberreadonly string[] | 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 |
items0.4.0Os itens a mostrar na lista. | readonly Value[] | readonly Group<Value>[] | sem padrão |
itemToStringValue0.4.0Quando 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.0Se o item destacado continua destacado quando o ponteiro sai da lista. | boolean | false |
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 |
mode0.4.0Como o autocompletar filtra a lista e completa o texto no próprio campo. | "both""inline""list""none" | "list" |
name0.4.0Identifica o campo quando o formulário é enviado. | string | 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: AutocompleteRootOpenChangeEventDetails) => 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 texto do campo do autocompletar muda. | ((value: string, eventDetails: AutocompleteRootChangeEventDetails) => 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 | false |
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 e do Combobox. | ControlSize | "md" |
submitOnItemClick0.4.0Se clicar num item envia o formulário do autocompletar. | boolean | false |
value0.4.0O texto do campo do autocompletar. | stringnumberreadonly string[] | sem padrão |
virtualized0.4.0Se os itens estão sendo virtualizados por fora. | boolean | false |