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.

Typically used for searching large or dynamic datasets. The data source is determined by the implementation — it may be a backend API, a large pre-loaded list, or any async data source. Unlike Select, the list is filtered on each keystroke.

In the Focus state, use the ContextMenu component as the dropdown. The spacing between the Autocomplete field and the ContextMenu is 4px in all sizes.

When to use

• When the user must select a value from a large or dynamic dataset that cannot be loaded all at once
• When a free-text search with suggestions speeds up data entry (e.g. city names, product search, user lookup)
• When valid values need to be filtered or validated as the user types

When not to use

• When the list is small and static — use a Select instead
• When the user can enter any free-form text without needing suggestions — use a plain Input
• When multiple values need to be selected simultaneously — use a MultiSelect

Content guidelines

• Placeholder should describe what the user is searching for: "Search city", "Find product" — not just "Search".
• Error messages should be specific: "No results found", "Select a valid option from the list" — not "Invalid value".
• Value text should show the selected item's human-readable label, not an ID or code.
• Do not show the Remove button in the Disable state — users cannot clear a disabled field.

ContextMenu integration

• The dropdown list is a separate ContextMenu component, not embedded in Autocomplete itself. Rules:
• Open on Focus; close on blur or item selection
• Position the ContextMenu 4px below the Autocomplete field, matching the field width
• Every keystroke should trigger a backend request to filter the list
• Show a loading indicator inside the ContextMenu while the request is in progress
• Show an empty state message when no results are found

Behaviour guidelines

• Debounce backend requests — wait ~200–300ms after the user stops typing before firing the request. This reduces server load and avoids flickering results.
• Minimum query length — consider requiring at least 1–2 characters before querying. Show a hint ("Type to search") in the dropdown if fewer characters are entered.
• Keyboard navigation — once the ContextMenu is open, arrow keys should move focus through options; Enter selects; Escape closes and returns focus to the input.
• Clear on re-focus — if the user focuses the field after a value is selected, either retain the value (for editing) or clear it to allow a new search. Document which behaviour the team has chosen.
• Selecting an item — selecting an option from the ContextMenu should populate the value, close the dropdown, and move the chevron back to down-state.
• Pasting — if the user pastes a value, trigger a search immediately.

Accessibility

• Use role="combobox" on the input, aria-expanded to reflect whether the dropdown is open, and aria-controls pointing to the ContextMenu list
• Use aria-autocomplete="list" to indicate that suggestions come from a list
• The ContextMenu list should use role="listbox" with role="option" on each item
• Arrow-key navigation must move aria-activedescendant on the input to match the focused option
• Icon left (search icon) is decorative — add aria-hidden="true"
• Remove button must have an accessible name: aria-label="Clear"
• Chevron is decorative — add aria-hidden="true". Use aria-expanded to communicate open/closed state
• Error message must be linked via aria-describedby so screen readers announce it on focus

Installation

npm install @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 | | :------------ | :-------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------ | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | 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