Autocomplete

Beta

Input-driven suggestions list with selectable options.

Installation

npm install @xaui/native

Import

import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

Basic Usage

Minimal example showing the component with its default configuration.

import { Autocomplete } from '@xaui/native/autocomplete'

export function Example() {
  return <Autocomplete />
}

Basic Autocomplete

Autocomplete with a list of items.

import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

export function BasicExample() {
  return (
    <Autocomplete label="Search framework" placeholder="Type to search">
      <AutocompleteItem value="react" label="React" />
      <AutocompleteItem value="vue" label="Vue" />
      <AutocompleteItem value="angular" label="Angular" />
      <AutocompleteItem value="svelte" label="Svelte" />
    </Autocomplete>
  )
}

Controlled Selection

Track the selected value with state.

import { useState } from 'react'
import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

const fruits = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' },
]

export function ControlledExample() {
  const [selected, setSelected] = useState<string | null>(null)

  return (
    <Autocomplete
      label="Select a fruit"
      onSelectionChange={setSelected}
    >
      {fruits.map(fruit => (
        <AutocompleteItem key={fruit.value} value={fruit.value} label={fruit.label} />
      ))}
    </Autocomplete>
  )
}

With Description & Error

Provide helper text and validation feedback.

import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

export function ValidationExample() {
  return (
    <Autocomplete
      label="Country"
      description="Select your country of residence"
      errorMessage="Country is required"
      isInvalid
    >
      <AutocompleteItem value="fr" label="France" />
      <AutocompleteItem value="us" label="United States" />
      <AutocompleteItem value="uk" label="United Kingdom" />
    </Autocomplete>
  )
}

Items with Description

Show secondary text inside each item.

import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

export function ItemDescriptionExample() {
  return (
    <Autocomplete label="Select role">
      <AutocompleteItem
        value="admin"
        label="Admin"
        description="Full access to all resources"
      />
      <AutocompleteItem
        value="editor"
        label="Editor"
        description="Can edit content, cannot manage users"
      />
      <AutocompleteItem
        value="viewer"
        label="Viewer"
        description="Read-only access"
        isDisabled
      />
    </Autocomplete>
  )
}

Allows Custom Value

Let users type values not present in the list.

import { Autocomplete, AutocompleteItem } from '@xaui/native/autocomplete'

export function CustomValueExample() {
  return (
    <Autocomplete label="Tag" allowsCustomValue placeholder="Choose or create a tag">
      <AutocompleteItem value="design" label="Design" />
      <AutocompleteItem value="engineering" label="Engineering" />
      <AutocompleteItem value="marketing" label="Marketing" />
    </Autocomplete>
  )
}