Autocomplete

Search and select from a list of options with keyboard navigation and filtering.

Import

import { Autocomplete } from 'asterui'

Examples

Basic Autocomplete

Simple autocomplete with string array options.

</>

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

With Object Options

Autocomplete with value/label object options.

</>

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

Controlled

Controlled autocomplete with state management.

</>

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

Allow Clear

Autocomplete with clear button.

</>

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

No Custom Values

Autocomplete that only allows selection from options.

</>

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

Custom Filter

Autocomplete with custom filtering logic (starts with).

</>

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

Different Sizes

Autocomplete in various sizes.

</>

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

Colors

Different color variants.

</>

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

Validation Status

Autocomplete with validation status for form feedback.

</>

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

Disabled

Disabled autocomplete.

</>

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

Disabled Options

Individual options can be disabled.

</>

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

Custom Not Found Content

Autocomplete with custom message when no results.

</>

import { Autocomplete } from 'asterui'

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

export default App

Email Domain Autocomplete

Practical example with email domain suggestions.

</>

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

In Form

Autocomplete integrated with Form component.

</>

Country*

 

Submit

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

Property	Description	Type	Default
value	Controlled value	string	-
defaultValue	Default value (uncontrolled)	string	''
onChange	Callback when value changes	(value: string) => void	-
onSelect	Callback when an option is selected	(value: string, option: AutocompleteOption) => void	-
onSearch	Callback when input value changes (for async filtering)	(value: string) => void	-
options	Array of options to display	string[] | AutocompleteOption[]	-
placeholder	Input placeholder text	string	"Type to search..."
disabled	Disable the autocomplete	boolean	false
size	Input size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
color	Input color variant	'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error'	-
status	Validation status (sets aria-invalid)	'error' | 'warning'	-
allowCustomValue	Allow user to enter custom values not in options	boolean	true
filterOption	Custom filter function	(option: AutocompleteOption, inputValue: string) => boolean	-
notFoundContent	Content to show when no options match	React.ReactNode	"No results found"
allowClear	Show clear button when input has value	boolean | { clearIcon?: ReactNode }	false
onClear	Callback when clear button is clicked	() => void	-
open	Controlled open state of dropdown	boolean	-
defaultOpen	Default open state (uncontrolled)	boolean	false
onOpenChange	Callback when open state changes	(open: boolean) => void	-
defaultActiveFirstOption	Activate first option by default when filtering	boolean	true
className	Additional CSS classes	string	-
data-testid	Test ID for testing	string	-

AutocompleteOption

Property	Description	Type	Default
value	The value of the option	string	-
label	The display text of the option	string	-
disabled	Whether the option is disabled	boolean	-
data-testid	Test ID for testing	string	-

Keyboard Navigation

• Up / Down - Navigate through options
• Enter - Select highlighted option
• Esc - Close dropdown and blur input

Accessibility

• Uses role="combobox" with proper ARIA attributes
• Dropdown uses role="listbox" with role="option" items
• aria-expanded indicates dropdown open state
• aria-activedescendant tracks the highlighted option
• aria-selected indicates the currently highlighted option
• Use status="error" to set aria-invalid automatically
• Disabled options use aria-disabled
• Clear button has aria-label for screen readers