Autocomplete

Busca y selecciona de una lista de opciones con navegación por teclado y filtrado.

Importar

import { Autocomplete } from 'asterui'

Ejemplos

Autocomplete Básico

Autocomplete simple con opciones de array de cadenas.

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

Con Opciones de Objeto

Autocomplete con opciones de objeto valor/etiqueta.

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 con gestión 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 Limpiar

Autocomplete con botón de limpiar.

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

Sin Valores Personalizados

Autocomplete que solo permite selección de opciones.

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 con lógica de filtrado personalizada (comienza con).

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 Tamaños

Autocomplete en varios tamaños.

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

Colores

Diferentes variantes de color.

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

Estado de Validación

Autocomplete con estado de validación para retroalimentación de formulario.

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

Deshabilitado

Autocomplete deshabilitado.

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

Opciones Deshabilitadas

Las opciones individuales pueden ser deshabilitadas.

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

Contenido Personalizado No Encontrado

Autocomplete con mensaje personalizado cuando no hay 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 Dominio de Email

Ejemplo práctico con sugerencias de dominio 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

En Formulario

Autocomplete integrado con el 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`

Propiedad	Descripción	Tipo	Predeterminado
`value`	Valor controlado	`string`	-
`defaultValue`	Valor predeterminado (no controlado)	`string`	`''`
`onChange`	Callback cuando cambia el valor	`(value: string) => void`	-
`onSelect`	Callback cuando se selecciona una opción	`(value: string, option: AutocompleteOption) => void`	-
`onSearch`	Callback cuando cambia el valor de entrada (para filtrado asíncrono)	`(value: string) => void`	-
`options`	Array de opciones a mostrar	`string[] \| AutocompleteOption[]`	-
`placeholder`	Texto de marcador de posición de entrada	`string`	`"Type to search..."`
`disabled`	Deshabilitar el autocomplete	`boolean`	`false`
`size`	Tamaño de entrada	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
`color`	Variante de color de entrada	`'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'`	-
`status`	Estado de validación (establece aria-invalid)	`'error' \| 'warning'`	-
`allowCustomValue`	Permitir al usuario ingresar valores personalizados que no están en las opciones	`boolean`	`true`
`filterOption`	Función de filtro personalizada	`(option: AutocompleteOption, inputValue: string) => boolean`	-
`notFoundContent`	Contenido a mostrar cuando no hay opciones coincidentes	`React.ReactNode`	`"No results found"`
`allowClear`	Mostrar botón de limpiar cuando la entrada tiene valor	`boolean \| { clearIcon?: ReactNode }`	`false`
`onClear`	Callback cuando se hace clic en el botón de limpiar	`() => void`	-
`open`	Estado abierto controlado del desplegable	`boolean`	-
`defaultOpen`	Estado abierto predeterminado (no controlado)	`boolean`	`false`
`onOpenChange`	Callback cuando cambia el estado abierto	`(open: boolean) => void`	-
`defaultActiveFirstOption`	Activar la primera opción por defecto al filtrar	`boolean`	`true`
`className`	Clases CSS adicionales	`string`	-
`data-testid`	ID de prueba para pruebas	`string`	-

`AutocompleteOption`

Propiedad	Descripción	Tipo	Predeterminado
`value`	El valor de la opción	`string`	-
`label`	El texto a mostrar de la opción	`string`	-
`disabled`	Si la opción está deshabilitada	`boolean`	-
`data-testid`	ID de prueba para pruebas	`string`	-

Navegación por Teclado

Arriba / Abajo - Navegar a través de las opciones
Enter - Seleccionar la opción resaltada
Esc - Cerrar el desplegable y desenfocar la entrada

Accesibilidad

Usa role="combobox" con atributos ARIA adecuados
El desplegable usa role="listbox" con elementos role="option"
aria-expanded indica el estado abierto del desplegable
aria-activedescendant rastrea la opción resaltada
aria-selected indica la opción actualmente resaltada
Usa status="error" para establecer aria-invalid automáticamente
Las opciones deshabilitadas usan aria-disabled
El botón de limpiar tiene aria-label para lectores de pantalla