Autocomplete

A cross-platform React autocomplete component that provides a filterable dropdown list of suggestions as the user types. Supports both simple string options and rich objects with icons and descriptions.

Installation

npm install @xsolla/xui-autocomplete
# or
yarn add @xsolla/xui-autocomplete

Demo

Basic Autocomplete

import * as React from 'react';
import { Autocomplete } from '@xsolla/xui-autocomplete';

export default function BasicAutocomplete() {
  const [value, setValue] = React.useState('');

  return (
    <Autocomplete
      value={value}
      onValueChange={setValue}
      options={['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry']}
      placeholder="Search fruits..."
    />
  );
}

Rich Options with Icons

import * as React from 'react';
import { Autocomplete } from '@xsolla/xui-autocomplete';
import { Settings, User } from '@xsolla/xui-icons';
import { LayoutDashboard } from '@xsolla/xui-icons-base';

export default function RichAutocomplete() {
  const [value, setValue] = React.useState('');

  const options = [
    { id: '1', label: 'Dashboard', description: 'View your dashboard', icon: <LayoutDashboard size={16} /> },
    { id: '2', label: 'Settings', description: 'Manage your settings', icon: <Settings size={16} /> },
    { id: '3', label: 'Profile', description: 'Edit your profile', icon: <User size={16} /> },
  ];

  return (
    <Autocomplete
      value={value}
      onValueChange={setValue}
      list={options}
      onSelect={(option) => console.log('Selected:', option)}
      placeholder="Search pages..."
    />
  );
}

Loading State

import * as React from 'react';
import { Autocomplete } from '@xsolla/xui-autocomplete';

export default function LoadingAutocomplete() {
  const [value, setValue] = React.useState('');
  const [loading, setLoading] = React.useState(false);
  const [options, setOptions] = React.useState([]);

  const handleSearch = async (query: string) => {
    setValue(query);
    if (query.length >= 2) {
      setLoading(true);
      // Simulate API call
      await new Promise(r => setTimeout(r, 500));
      setOptions(['Result 1', 'Result 2', 'Result 3']);
      setLoading(false);
    }
  };

  return (
    <Autocomplete
      value={value}
      onValueChange={handleSearch}
      options={options}
      isLoading={loading}
      placeholder="Type to search..."
    />
  );
}

Anatomy

import { Autocomplete } from '@xsolla/xui-autocomplete';

<Autocomplete
  value={inputValue}           // Input text value
  onValueChange={setValue}     // Input change handler
  options={['a', 'b']}         // Simple string options
  list={[{id, label, ...}]}    // Rich options with metadata
  onSelect={handleSelect}      // Selection handler
  isLoading={false}            // Show loading spinner
  placeholder="Search..."      // Placeholder text
  size="md"                     // Size variant
  label="Label"                // Label above input
  errorLabel="Error"           // Error message
  state="default"              // Visual state
  maxHeight={200}              // Dropdown max height
  emptyMessage="No results"    // Empty state message
/>

API Reference

Autocomplete

Autocomplete Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | value | string | - | Current input value. | | onValueChange | (value: string) => void | - | Input change handler. | | options | string[] | - | Simple string options array. | | list | AutocompleteOption[] | - | Rich options with metadata. | | onSelect | (option: string \| AutocompleteOption) => void | - | Selection handler. | | isLoading | boolean | false | Show loading spinner. | | placeholder | string | - | Input placeholder text. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" | "md" | Component size. | | state | "default" \| "hover" \| "focus" \| "disable" \| "error" | "default" | Visual state. | | label | string | - | Label above input. | | errorLabel | string | - | Error message below input. | | iconLeft | ReactNode | - | Icon on left side. | | chevronRight | boolean | - | Show chevron on right. | | filled | boolean | - | Filled background style. | | maxHeight | number | - | Dropdown max height in px. | | dropdownWidth | number \| string | - | Custom dropdown width. | | emptyMessage | string | - | Message when no results. |

AutocompleteOption:

interface AutocompleteOption {
  id: string;           // Unique identifier
  label: string;        // Display text
  description?: string; // Optional description
  icon?: ReactNode;     // Optional leading icon
  disabled?: boolean;   // Disabled state
}

Keyboard Navigation

| Key | Action | | :-- | :----- | | Arrow Down | Move to next option | | Arrow Up | Move to previous option | | Enter | Select highlighted option | | Escape | Close dropdown |

Accessibility

• Uses role="combobox" pattern
• aria-expanded indicates dropdown state
• aria-autocomplete="list" for screen readers
• Options have proper focus management