AutoComplete

Um campo de seleção com busca, sugestões dinâmicas, criação de opções personalizadas e carregamento incremental.

Visão Geral

  • Suporte a busca com filtro customizável.
  • Criação de opções personalizadas com canCreate e onCreate.
  • Scroll infinito com onEndReached.
  • Suporte a modo headless ou com popover modal.
  • Indica carregamento com loading e passiveLoading.
  • Possui versão com renderização externa de label com renderOutside e Caption.

Utilização

index.tsx
import { AutoComplete } from "@convertcompany/ui";

Exemplos

Com itens customizados

O AutoComplete permite renderizar opções de forma customizada. Para isso, utilize a prop renderItem e retorne o JSX desejado.

Com trigger customizado

Você pode personalizar o gatilho do AutoComplete utilizando a prop children. Isso permite que você use qualquer componente como gatilho, mantendo a funcionalidade do AutoComplete.

Use qualquer componente como gatilho

Com criação de opção

O AutoComplete permite criar novas opções com base na busca. Para isso, utilize a prop canCreate e onCreate. O texto exibido ao criar uma nova opção pode ser customizado com a prop createItemText, onde {search} será substituído pelo termo buscado. Além disso é possível customizar o ícone ao lado do texto de criação de item com a prop createItemIcon.

Pressione Enter para criar uma nova opção

Com scroll infinito

O AutoComplete permite carregar opções de forma assíncrona com scroll infinito. Para isso, utilize a prop onEndReached para carregar mais opções quando o usuário chegar ao final da lista. Você pode usar a prop loading para indicar que as opções estão sendo carregadas.

Realize scroll até o final

Com filtro customizado

Você pode personalizar o filtro de opções utilizando a prop filterBy. Essa função recebe o valor da opção, o termo buscado e as palavras-chave. O retorno deve ser um número que indica a relevância da opção (quanto maior, mais relevante). Você também pode usar a prop canFilter para habilitar o campo de busca dentro do menu.

Com carregamento

Além de adicionar um feedback de loading, a prop passiveLoading pode ser utilizado para impedir que o usuário interaja com as opções enquanto o carregamento está ativo. Caso contrário, o usuário pode ver as opções enquanto o carregamento está ativo. Você também pode usar a prop loadingStateText para exibir um texto personalizado durante o carregamento.

passiveLoading desabiltado
passiveLoading habilitado (default)

Props

PropriedadeTipo
optionsLista de opções disponíveis para seleção. Cada opção deve conter value e label.
Option[]
valueValor selecionado atualmente.
string
null
onChangeCallback acionado ao alterar o valor selecionado.
(value: string | null) => void
placeholderTexto exibido quando nenhuma opção está selecionada.
string
canClearPermite limpar a seleção. Padrão é true.
boolean
canCreatePermite criar uma nova opção com base na busca.
boolean
createItemTextTexto exibido ao criar nova opção. Use {search} para o termo buscado.
string
createItemIconÍcone exibido ao lado do texto de criação de item.
ReactNode
onCreateCallback acionado ao criar nova opção.
(value: string) => void
canFilterHabilita o campo de busca dentro do menu.
boolean
filterByFunção customizada de filtro. Se retornar false, o filtro será desabilitado.
(value: string, search: string, keywords?: string[]) => number | false
onSearchCallback acionado a cada alteração no campo de busca.
(value: string) => void
loopPermite loop ao navegar com teclado.
boolean
renderItemPermite renderização customizada das opções.
(option: Option) => ReactNode
renderOutsideRenderiza o valor fora do campo de entrada.
boolean
classNameClasse CSS adicional.
string
modalPopoverAtiva modo modal do popover (Radix).
boolean
emptyStateTextTexto exibido quando não há resultados.
string
loadingIndica estado de carregamento.
boolean
passiveLoadingMostra o carregamento mesmo com resultados visíveis.
boolean
loadingStateTextTexto exibido durante carregamento.
string
renderValueRenderização customizada do valor.
(value: string) => ReactNode
onEndReachedCallback acionado ao chegar no final da lista (scroll infinito).
() => void
childrenTrigger customizado para o AutoComplete.
ReactNode