XDS — Design System

XDSTypeaheadItem@xds/core · Typeahead

Preview coming soon

Usage

A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.

Best practices

Guidance	Practices
Do	Provide descriptive placeholder text that hints at what users can search for.
Do	Show suggestions on focus when users benefit from seeing popular or recent options before typing.
Do	Add a search delay for remote data sources to avoid excessive network requests.
Don't	Use for short, static option lists — use Selector for better discoverability.
Don't	Use for multi-selection — use Tokenizer instead.
Don't	Place multiple Typeaheads adjacent to each other without clear labels differentiating them.

Import

ts
import {XDSTypeaheadItem} from '@xds/core/Typeahead'

Props

Prop	Type	Description
itemrequired	XDSSearchableItem	The search result item to render.
icon	ReactNode	Icon or avatar to display before the label.
description	string	Description text displayed below the label.
isDisabled	boolean (default: false)	Whether this item is visually disabled.
group	string	Group label for grouping items visually.

Showcase source

tsx
'use client';
import {useState} from 'react';
import {XDSTypeahead, XDSTypeaheadItem} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
import {XDSAvatar} from '@xds/core/Avatar';
import {XDSCenter} from '@xds/core/Center';
interface PersonItem extends XDSSearchableItem {
  auxiliaryData: {role: string};
}
const people: PersonItem[] = [
  {id: '1', label: 'Alice Johnson', auxiliaryData: {role: 'Engineer'}},
  {id: '2', label: 'Bob Smith', auxiliaryData: {role: 'Designer'}},
  {id: '3', label: 'Charlie Brown', auxiliaryData: {role: 'Product Manager'}},
  {id: '4', label: 'Diana Prince', auxiliaryData: {role: 'Data Scientist'}},
  {id: '5', label: 'Eve Davis', auxiliaryData: {role: 'QA Engineer'}},
];
const peopleSource: XDSSearchSource<PersonItem> = {
  search: (query: string) =>
    people.filter(p => p.label.toLowerCase().includes(query.toLowerCase())),
  bootstrap: () => people.slice(0, 4),
};
export default function TypeaheadItemShowcase() {
  const [value, setValue] = useState<PersonItem | null>(null);
  return (
    <XDSCenter width={320}>
      <XDSTypeahead
        label="Assignee"
        placeholder="Search people..."
        searchSource={peopleSource}
        value={value}
        onChange={setValue}
        renderItem={(item: PersonItem) => (
          <XDSTypeaheadItem
            item={item}
            icon={<XDSAvatar name={item.label} size="small" />}
            description={item.auxiliaryData.role}
          />
        )}
      />
    </XDSCenter>
  );
}