SelectAutocomplete

Campo de seleção com funcionalidade de autocomplete que permite ao usuário filtrar opções digitando no campo de entrada.

Importação

import { SelectAutocomplete } from '@useblu/ocean-react';

Importação específica (recomendado para tree-shaking)

import { SelectAutocomplete } from '@useblu/ocean-react/Select';

Importação de tipos TypeScript

import type { SelectProps } from '@useblu/ocean-react';

// Uso em componente customizado
const MyComponent: React.FC<SelectProps> = (props) => {
  return <SelectAutocomplete {...props} />;
};

Playground Interativo

Explore o componente SelectAutocomplete no playground interativo do Storybook:

🚀 Abrir no Storybook

Documentação Completa

Para documentação técnica detalhada, exemplos de uso e API completa, consulte o Storybook do SelectAutocomplete.

No Storybook você encontrará:

• ✅ Controles interativos para testar todas as props
• ✅ API gerada automaticamente com tipagem completa
• ✅ Exemplos visuais de todas as variantes e estados
• ✅ Playground para experimentação rápida

Uso básico

<SelectAutocomplete
  label="País"
  placeholder="Digite para buscar..."
  options={[
    { value: 'br', label: 'Brasil' },
    { value: 'us', label: 'Estados Unidos' },
    { value: 'ca', label: 'Canadá' },
    { value: 'mx', label: 'México' },
  ]}
  onChange={(option) => console.log('Selecionado:', option)}
/>

Estados

O componente suporta diferentes estados visuais:

🚀 Abrir no Storybook

Estados disponíveis

• Normal: Estado padrão para seleção com filtro
• Com valor selecionado: Quando uma opção já está selecionada
• Disabled: Quando o campo não está disponível para digitação ou seleção
• Error: Quando há erro de validação

Opções Desabilitadas

É possível desabilitar opções específicas dentro do menu:

🚀 Abrir no Storybook

Conjunto Grande de Dados

O componente é ideal para trabalhar com listas grandes de opções:

🚀 Abrir no Storybook

Exemplos de Uso

SelectAutocomplete Controlado

const [selectedCountry, setSelectedCountry] = useState('');
const [filteredOptions, setFilteredOptions] = useState(countries);

const countries = [
  { value: 'br', label: 'Brasil' },
  { value: 'us', label: 'Estados Unidos' },
  { value: 'ca', label: 'Canadá' },
  { value: 'mx', label: 'México' },
  { value: 'ar', label: 'Argentina' },
  // ... mais países
];

return (
  <SelectAutocomplete
    label="País"
    placeholder="Digite para buscar..."
    value={selectedCountry}
    options={countries}
    onChange={(option) => setSelectedCountry(option.value)}
  />
);

SelectAutocomplete com Estados Brasileiros

const brazilianStates = [
  { value: 'sp', label: 'São Paulo' },
  { value: 'rj', label: 'Rio de Janeiro' },
  { value: 'mg', label: 'Minas Gerais' },
  { value: 'rs', label: 'Rio Grande do Sul' },
  { value: 'pr', label: 'Paraná' },
  { value: 'sc', label: 'Santa Catarina' },
  // ... todos os estados
];

return (
  <SelectAutocomplete
    label="Estado"
    placeholder="Digite o nome do estado..."
    helperText="Digite algumas letras para filtrar os estados"
    options={brazilianStates}
    onChange={(option) => console.log('Estado selecionado:', option)}
  />
);

SelectAutocomplete com Validação

const [selectedValue, setSelectedValue] = useState('');
const [hasError, setHasError] = useState(false);

const handleChange = (option) => {
  setSelectedValue(option.value);
  setHasError(false);
};

const handleSubmit = () => {
  if (!selectedValue) {
    setHasError(true);
  }
};

return (
  <form onSubmit={handleSubmit}>
    <SelectAutocomplete
      label="Cidade obrigatória"
      placeholder="Digite para buscar cidades..."
      value={selectedValue}
      options={cities}
      error={hasError}
      helperText={
        hasError ? 'Este campo é obrigatório' : 'Digite para filtrar as cidades'
      }
      onChange={handleChange}
    />
    <Button type="submit">Enviar</Button>
  </form>
);

SelectAutocomplete para APIs

const [options, setOptions] = useState([]);
const [loading, setLoading] = useState(false);

const searchCities = async (query) => {
  if (query.length < 2) return;

  setLoading(true);
  try {
    const response = await fetch(`/api/cities?q=${query}`);
    const cities = await response.json();
    setOptions(
      cities.map((city) => ({
        value: city.id,
        label: city.name,
      }))
    );
  } catch (error) {
    console.error('Erro ao buscar cidades:', error);
  } finally {
    setLoading(false);
  }
};

return (
  <SelectAutocomplete
    label="Cidade"
    placeholder="Digite para buscar cidades..."
    options={options}
    disabled={loading}
    helperText={loading ? 'Buscando...' : 'Digite pelo menos 2 caracteres'}
    onChange={(option) => console.log('Cidade selecionada:', option)}
  />
);

API

Props

Prop	Tipo	Padrão	Descrição
options	OptionType[]	-	Array de opções que populam o menu (obrigatório)
label	string	-	Rótulo do campo de seleção
placeholder	string	-	Texto exibido no campo de entrada
value	string | number	-	Valor selecionado (modo controlado)
defaultValue	string | number	-	Valor padrão selecionado (modo não controlado)
onChange	(option: OptionType) => void	-	Callback quando uma opção é selecionada
error	boolean	false	Exibe estilo de erro
disabled	boolean	false	Desabilita o campo
helperText	string	-	Texto de ajuda exibido abaixo do campo
id	string	-	ID do elemento select
name	string	-	Nome do campo para formulários
ariaLabel	string	-	Label de acessibilidade
className	string	-	Classes CSS adicionais

OptionType

type OptionType = {
  value: string | number;
  label: string;
  disabled?: boolean;
  className?: string;
  [propName: string]: any;
};

Eventos

• onChange: Disparado quando uma opção é selecionada
• Suporte a eventos padrão de input (onFocus, onBlur, etc.)

Funcionalidades

Filtro Automático

• Busca case-insensitive: Não diferencia maiúsculas de minúsculas
• Busca por substring: Encontra correspondências em qualquer parte do label
• Filtro em tempo real: Atualiza a lista conforme digita

Navegação por Teclado

• Digite: Filtra as opções automaticamente
• Arrow Up/Down: Navega pelas opções filtradas
• Enter: Seleciona a opção em destaque
• Escape: Fecha o menu e limpa o filtro
• Tab: Move foco para próximo elemento

Comportamento do Input

• Seleção: Ao selecionar uma opção, o input mostra o label selecionado
• Edição: Ao começar a digitar, o filtro é ativado
• Reset: Limpar o input remove a seleção atual

Acessibilidade

• ✅ Suporte completo a navegação por teclado
• ✅ Estados de foco visíveis
• ✅ Atributos ARIA apropriados
• ✅ Suporte a screen readers
• ✅ Labels associados corretamente
• ✅ Feedback sobre resultados da busca
• ✅ Contraste adequado em todos os estados

Navegação por teclado

Tecla	Função
Tab	Move foco para o campo
Digite	Filtra opções automaticamente
Arrow Up/Down	Navega pelas opções filtradas
Enter	Seleciona a opção em destaque
Escape	Fecha o menu e limpa filtro
Backspace	Remove caracteres e atualiza filtro

Melhores práticas

✅ Faça

• Use para listas com mais de 10 opções
• Forneça placeholder que indique a funcionalidade de busca
• Use helperText para orientar sobre o filtro
• Implemente debounce para buscas em APIs
• Ordene resultados por relevância
• Limite o número de resultados exibidos

❌ Não faça

• Não use para poucas opções (prefira Select simples)
• Não implemente filtro muito restritivo
• Não ignore estados de loading para buscas em API
• Não omita feedback sobre resultados da busca
• Não faça requests a cada caractere digitado

Diferenças do Select

Funcionalidade	Select	SelectAutocomplete
Filtro de opções	❌	✅
Campo de entrada	❌	✅
Melhor para	Poucas opções	Muitas opções
Navegação	Apenas teclado	Teclado + digitação
Performance	Melhor	Boa (com muitas opções)

Classes CSS

Classe	Descrição
.ods-select-autocomplete__root	Estilos aplicados ao elemento raiz
.ods-select-autocomplete__arrow	Estilos aplicados ao ícone de seta
.ods-select-autocomplete__arrow--up	Estilos aplicados quando o menu está aberto
.ods-select-autocomplete__arrow--down	Estilos aplicados quando o menu está fechado
.ods-select-autocomplete__arrow--disabled	Estilos aplicados no estado desabilitado

Links relacionados

• Select - Para seleção simples sem filtro
• Input - Para entrada de texto livre
• Button - Para ações de formulário
• Storybook - SelectAutocomplete - Documentação técnica