Typeahead

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.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Base Typeahead

Composable combobox engine providing a bare input, search, keyboard navigation, and a styled result dropdown. It renders no input wrapper, border, or selected-value token. Typeahead and Tokenizer compose it for standard fields.

Usage guidance

• Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with input chrome and selected-value rendering it intentionally omits.
• Provide your own visible label or aria-label and custom input wrapper so the bare combobox has an accessible name, focus treatment, border, and layout.
• Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.
• Avoid: Expect input chrome or selected-value rendering. BaseTypeahead is an engine; the caller owns those visible parts.
• Avoid: Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.
• Avoid: Treat Escape as cancellation of pending source work. It hides the current popup, but a late response can reopen it.

Anatomy

• Input: Bare combobox input. The caller supplies its visible field chrome and accessible name.
• Loading status: Named Spinner shown beside the input while an asynchronous source is pending, unless a composed owner takes over the busy indicator lane.
• Dropdown: Anchored listbox surface containing current search or bootstrap results.
• Empty state: Disabled listbox option shown after a completed search returns no results.
• Result group heading: Visible label for a group of result options.
• Result row: Option wrapper that owns highlight, selection, pointer, and keyboard behavior.
• Default item content: TypeaheadItem label and optional supporting content rendered inside a result row.
• Caller-rendered item content: Caller content supplied through renderItem or item.element inside the stable result row.
• Selected result state: Selected row weight and trailing check shown when a result matches value.

Typeahead

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.

Usage guidance

• Provide descriptive placeholder text that hints at what users can search for.
• Show suggestions on focus when users benefit from seeing popular or recent options before typing.
• Add a search delay for remote data sources to avoid excessive network requests.
• Use inside InputGroup when the typeahead needs a single-line prefix or suffix addon.
• Avoid: Use for short, static option lists; use Selector for better discoverability.
• Avoid: Use for multi-selection; use Tokenizer instead.
• Avoid: Place multiple Typeaheads adjacent to each other without clear labels differentiating them.
• Avoid: Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-typeahead",
      "visualProps": [
        "status",
        "size"
      ]
    },
    {
      "className": "astryx-typeahead-dropdown"
    },
    {
      "className": "astryx-typeahead-empty-state"
    },
    {
      "className": "astryx-typeahead-item"
    }
  ]
}

BaseTypeahead

TypeaheadItem

Anatomy

• Field: Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.
• Input surface: Painted control surface containing the editable input or the selected token.
• Icon-rendered start icon: Optional leading semantic icon or icon component rendered through Icon.
• Caller-rendered start content: Optional arbitrary React content rendered directly at the start of the input surface.
• Selected token: Token that presents the selected item while the control is not in edit mode.
• Spinner: Loading indicator shown at the end of the input surface while a search is in flight.
• Clear button: Shared clear action that removes the selected item when hasClear is enabled.
• Dropdown: Anchored listbox surface containing the current search results.
• Empty state: Message shown after a completed search returns no results.
• Result row: Stable option wrapper that owns highlight, selection, pointer, and keyboard behavior.
• Default item content: Standard TypeaheadItem label and supporting content rendered inside a result row when renderItem and item.element are absent.
• Caller-rendered item content: Caller-owned result content supplied through renderItem or item.element inside the stable result row.
• Result group heading: Visible heading for a labeled group of result rows.
• Selected result state: Selected styling and trailing check presented on the current result row.

Typeahead Item

Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.

Examples

• BaseTypeahead — Custom Search Bar: BaseTypeahead embedded inside a custom-styled wrapper. The wrapper provides its own border and icon chrome; anchorRef positions the dropdown relative to it. Use this pattern when Typeahead's built-in field layout does not fit your composition.
• Typeahead Item: Typeahead with custom item rendering using TypeaheadItem for avatars and descriptions.
• Typeahead:
• Base Typeahead: A custom result renderer that adds supporting metadata while BaseTypeahead retains option semantics and keyboard behavior.
• TypeaheadItem — Basic: A typeahead whose results are rendered with TypeaheadItem, adding a secondary description below each label. Use inside renderItem to keep custom results visually consistent.
• Typeahead — Limited Results: Typeahead with a capped dropdown showing at most three results.
• Typeahead — Search Field: Search input with icon and suggestions on focus.
• Typeahead — With Helper Text: Typeahead with a description below the label.
• Typeahead — With Validation: Typeahead with an error validation message.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0

Source StyleX compilation

BaseTypeaheadCustomSearch, BaseTypeaheadShowcase contain stylex.create and require a StyleX source build pipeline. Precompiled Core CSS alone does not compile these examples. See Styling before copying them.