Pharos
Navegar componentes
← Componentes

Typeahead

TypeaheadExemplo
Um input pesquisável para selecionar um único item de um dataset grande ou dinâmico. Resultados aparecem conforme o usuário digita, com suporte a fontes de dados assíncronas, busca com debounce e renderização personalizada de itens. Use-o quando a lista de opções for grande demais para um dropdown Selector.
Importação
import {Typeahead} from '@pharos-ds/core/Typeahead';

Exemplos

Área interativa

size
isDisabled
hasEntriesOnFocus
Código
import {Typeahead} from '@pharos-ds/core/Typeahead';

<Typeahead
  size="md"
  isDisabled={false}
  hasEntriesOnFocus={false}
 />

Boas práticas

  • Faça: Forneça placeholder text descritivo que sugira o que usuários podem buscar.
  • Faça: Mostre suggestions no focus quando usuários se beneficiarem de ver opções populares ou recentes antes de digitar.
  • Faça: Adicione um search delay para fontes de dados remotas para evitar requisições de rede excessivas.
  • Faça: Use dentro de InputGroup quando o typeahead precisar de um addon prefix ou suffix de uma linha.
  • Evite: Use para listas de opções curtas e estáticas; use Selector para melhor descoberta.
  • Evite: Use para multi-seleção; use Tokenizer em vez disso.
  • Evite: Coloque múltiplos Typeaheads adjacentes sem labels claros que os diferenciem.
  • Evite: Envolva um Typeahead desabilitado em Tooltip para explicar por que está desabilitado; triggers desabilitados engolem os eventos de hover que o wrapper precisa. Use a prop disabledMessage em vez disso.

Props

PropTipoPadrãoDescrição
label *string—Label acessível para o input.
searchSource *SearchSource<T>—Fonte de dados fornecendo métodos search e bootstrap para popular o dropdown.
value *T | null—Item atualmente selecionado, ou null se nada estiver selecionado.
onChange *(item: T | null) => void—Chamado quando a seleção muda.
placeholderstring—Texto placeholder do input.
hasEntriesOnFocusbooleanfalseMostra resultados bootstrap no focus antes de digitar.
hasClearbooleantrueMostra botão de limpar para desselecionar o value atual.
isDisabledbooleanfalseDesabilita o input.
disabledMessagestring—Explica por que o input está desabilitado. Com isDisabled, exibe um tooltip no hover/foco via teclado e mantém o campo focável via aria-disabled (ativação permanece bloqueada). Use isto em vez de envolver um Typeahead desabilitado em Tooltip. Controles desabilitados engolem os eventos de hover que um Tooltip externo precisa.
maxMenuItemsnumber10Número máximo de itens de dropdown a exibir.
status{type: 'warning' | 'error' | 'success', message?: string}—Objeto de status de validação com type e message para estados de error/warning/success.
statusVariant'attached' | 'detached''attached'Como a mensagem de status é posicionada em relação ao input. attached sobrepõe diretamente abaixo do input (tratamento com borda); detached flutua abaixo como elemento separado com espaçamento.
renderItem(item: T) => ReactNode—Função de renderização personalizada para itens de dropdown. O padrão renderiza TypeaheadItem.
isLabelHiddenbooleanfalseOculta visualmente o label mantendo-o acessível.
descriptionstring—Texto auxiliar exibido abaixo do label.
isRequiredbooleanfalseMarca o campo como obrigatório.
isOptionalbooleanfalseExibe um indicador optional no label.
labelTooltipstring—Texto de tooltip exibido no label.
emptySearchResultsTextstring'No results found'Texto exibido quando a busca não retorna resultados.
hasAutoFocusbooleanfalseAuto-focus no input ao montar.
size'sm' | 'md' | 'lg''md'Size do input e token.
debounceMsnumber150Atraso de debounce em ms antes de disparar a busca. Defina como 0 para fontes síncronas.
onChangeQuery(query: string) => void—Callback disparado quando o texto da query de busca muda.
onOpenChange(isOpen: boolean) => void—Callback quando o dropdown abre ou fecha.
widthSizeValue—Largura do campo (número = pixels, string usada como está, ex.: "100%"). Dimensiona o campo inteiro (label, controle e status) para que permaneçam alinhados.
xstyleStyleXStyles—Estilos StyleX para customização de layout (margens, posicionamento, dimensionamento). Deve ser um valor stylex.create(): não um objeto de estilo inline como style={{}}.
Pacote: @pharos-ds/core · Import: @pharos-ds/core/Typeahead
Typeahead · Pharos