Autocomplete

Pesquisar e selecionar de uma lista de opções com navegação por teclado e filtragem.

Importação

import { Autocomplete } from 'asterui'

Exemplos

Autocomplete Básico

Autocomplete simples com opções de array de strings.

import { Autocomplete } from 'asterui'

function App() {
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
    'Germany',
    'France',
  ]
  
  return (
      <Autocomplete
        options={countries}
        placeholder="Select a country"
      />
    )
}

export default App

Com Opções de Objeto

Autocomplete com opções de objeto valor/label.

import { Autocomplete } from 'asterui'

function App() {
  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
    { value: 'orange', label: 'Orange' },
  ]
  
  return (
      <Autocomplete
        options={fruits}
        placeholder="Select a fruit"
      />
    )
}

export default App

Controlado

Autocomplete controlado com gerenciamento de estado.

Selected: None

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [country, setCountry] = useState('')
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
  ]
  
  return (
      <div>
        <Autocomplete
          value={country}
          onChange={setCountry}
          options={countries}
          placeholder="Select a country"
        />
        <p className="mt-2 text-sm text-base-content/70">
          Selected: {country || 'None'}
        </p>
      </div>
    )
}

export default App

Permitir Limpar

Autocomplete com botão de limpar.

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [value, setValue] = useState('Apple')
  const fruits = ['Apple', 'Banana', 'Cherry', 'Orange']
  
  return (
      <Autocomplete
        value={value}
        onChange={setValue}
        options={fruits}
        allowClear
        placeholder="Select a fruit"
      />
    )
}

export default App

Sem Valores Personalizados

Autocomplete que só permite seleção das opções.

import { Autocomplete } from 'asterui'

function App() {
  const languages = [
    'JavaScript',
    'TypeScript',
    'Python',
    'Java',
    'C++',
  ]
  
  return (
      <Autocomplete
        options={languages}
        allowCustomValue={false}
        placeholder="Select a language"
      />
    )
}

export default App

Filtro Personalizado

Autocomplete com lógica de filtragem personalizada (começa com).

import { Autocomplete } from 'asterui'

function App() {
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
  ]
  
  return (
      <Autocomplete
        options={countries}
        filterOption={(option, input) =>
          option.label.toLowerCase().startsWith(input.toLowerCase())
        }
        placeholder="Type to filter (starts with)"
      />
    )
}

export default App

Diferentes Tamanhos

Autocomplete em vários tamanhos.

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <Autocomplete size="xs" options={options} placeholder="Extra small" />
        <Autocomplete size="sm" options={options} placeholder="Small" />
        <Autocomplete size="md" options={options} placeholder="Medium" />
        <Autocomplete size="lg" options={options} placeholder="Large" />
        <Autocomplete size="xl" options={options} placeholder="Extra large" />
      </Space>
    )
}

export default App

Cores

Diferentes variantes de cor.

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <Autocomplete color="primary" options={options} placeholder="Primary" />
        <Autocomplete color="secondary" options={options} placeholder="Secondary" />
        <Autocomplete color="accent" options={options} placeholder="Accent" />
        <Autocomplete color="success" options={options} placeholder="Success" />
        <Autocomplete color="warning" options={options} placeholder="Warning" />
        <Autocomplete color="error" options={options} placeholder="Error" />
      </Space>
    )
}

export default App

Status de Validação

Autocomplete com status de validação para feedback de formulário.

This field is required

Please verify this value

import { Autocomplete, Space } from 'asterui'

function App() {
  const options = ['Option 1', 'Option 2', 'Option 3']
  
  return (
      <Space direction="vertical" size="sm">
        <div>
          <Autocomplete status="error" options={options} placeholder="Error status" />
          <p className="text-error text-sm mt-1">This field is required</p>
        </div>
        <div>
          <Autocomplete status="warning" options={options} placeholder="Warning status" />
          <p className="text-warning text-sm mt-1">Please verify this value</p>
        </div>
      </Space>
    )
}

export default App

Desabilitado

Autocomplete desabilitado.

import { Autocomplete } from 'asterui'

function App() {
  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
  ]
  
  return (
      <Autocomplete
        options={fruits}
        disabled
        defaultValue="apple"
      />
    )
}

export default App

Opções Desabilitadas

Opções individuais podem ser desabilitadas.

import { Autocomplete } from 'asterui'

function App() {
  const options = [
    { value: 'opt1', label: 'Available option' },
    { value: 'opt2', label: 'Disabled option', disabled: true },
    { value: 'opt3', label: 'Another available' },
  ]
  
  return (
      <Autocomplete
        options={options}
        placeholder="Some options are disabled"
      />
    )
}

export default App

Conteúdo Não Encontrado Personalizado

Autocomplete com mensagem personalizada quando não há resultados.

import { Autocomplete } from 'asterui'

function App() {
  return (
      <Autocomplete
        options={['Apple', 'Banana', 'Cherry']}
        notFoundContent="Sorry, no matches found!"
        placeholder="Search fruits"
      />
    )
}

export default App

Autocomplete de Domínio de Email

Exemplo prático com sugestões de domínio de email.

Email: None

import { Autocomplete } from 'asterui'
import { useState } from 'react'

function App() {
  const [email, setEmail] = useState('')
  
  const domains = ['@gmail.com', '@yahoo.com', '@outlook.com', '@hotmail.com']
  
  const emailOptions = email.includes('@')
    ? domains.map(domain => email.split('@')[0] + domain)
    : domains.map(domain => email + domain)
  
  return (
      <div>
        <Autocomplete
          value={email}
          onChange={setEmail}
          options={emailOptions}
          placeholder="Enter email address"
        />
        <p className="mt-2 text-sm text-base-content/70">
          Email: {email || 'None'}
        </p>
      </div>
    )
}

export default App

Em Formulário

Autocomplete integrado com componente Form.

import { Autocomplete, Form, Button, Modal } from 'asterui'

function App() {
  const handleSubmit = (values: { country: string }) => {
    Modal.success({
      title: 'Form Submitted',
      content: `Country: ${values.country}`,
    })
  }
  
  return (
      <Form onFinish={handleSubmit} initialValues={{ country: 'Canada' }}>
        <Form.Item
          name="country"
          label="Country"
          required
          rules={{ required: 'Please select a country' }}
        >
          <Autocomplete
            options={['United States', 'Canada', 'United Kingdom']}
            placeholder="Select a country"
          />
        </Form.Item>
  
        <Form.Item>
          <Button htmlType="submit" color="primary">
            Submit
          </Button>
        </Form.Item>
      </Form>
    )
}

export default App

API

`Autocomplete`

Propriedade	Descrição	Tipo	Padrão
`value`	Valor controlado	`string`	-
`defaultValue`	Valor padrão (não controlado)	`string`	`''`
`onChange`	Callback quando o valor muda	`(value: string) => void`	-
`onSelect`	Callback quando uma opção é selecionada	`(value: string, option: AutocompleteOption) => void`	-
`onSearch`	Callback quando o valor de entrada muda (para filtragem assíncrona)	`(value: string) => void`	-
`options`	Array de opções para exibir	`string[] \| AutocompleteOption[]`	-
`placeholder`	Texto placeholder do input	`string`	`"Type to search..."`
`disabled`	Desabilitar o autocomplete	`boolean`	`false`
`size`	Tamanho do input	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
`color`	Variante de cor do input	`'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'`	-
`status`	Status de validação (define aria-invalid)	`'error' \| 'warning'`	-
`allowCustomValue`	Permitir que o usuário insira valores personalizados não nas opções	`boolean`	`true`
`filterOption`	Função de filtro personalizada	`(option: AutocompleteOption, inputValue: string) => boolean`	-
`notFoundContent`	Conteúdo para mostrar quando nenhuma opção corresponde	`React.ReactNode`	`"No results found"`
`allowClear`	Mostrar botão de limpar quando o input tem valor	`boolean \| { clearIcon?: ReactNode }`	`false`
`onClear`	Callback quando o botão de limpar é clicado	`() => void`	-
`open`	Estado aberto controlado do dropdown	`boolean`	-
`defaultOpen`	Estado aberto padrão (não controlado)	`boolean`	`false`
`onOpenChange`	Callback quando o estado aberto muda	`(open: boolean) => void`	-
`defaultActiveFirstOption`	Ativar primeira opção por padrão ao filtrar	`boolean`	`true`
`className`	Classes CSS adicionais	`string`	-
`data-testid`	ID de teste para testes	`string`	-

`AutocompleteOption`

Propriedade	Descrição	Tipo	Padrão
`value`	O valor da opção	`string`	-
`label`	O texto de exibição da opção	`string`	-
`disabled`	Se a opção está desabilitada	`boolean`	-
`data-testid`	ID de teste para testes	`string`	-

Navegação por Teclado

Seta para Cima / Baixo - Navegar pelas opções
Enter - Selecionar opção destacada
Esc - Fechar dropdown e desfocar input

Acessibilidade

Usa role="combobox" com atributos ARIA apropriados
Dropdown usa role="listbox" com itens role="option"
aria-expanded indica estado aberto do dropdown
aria-activedescendant rastreia a opção destacada
aria-selected indica a opção atualmente destacada
Use status="error" para definir aria-invalid automaticamente
Opções desabilitadas usam aria-disabled
Botão de limpar tem aria-label para leitores de tela