EXEPERTAI LAB

Research alpha

Time Machine
EXEPERTAI LAB
GALLERY / COLLECTION
← Browse Astryx gallery
Typeahead·component·@astryxdesign/core

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.

Open in Playground @astryxdesign/core/Typeahead

Showcases and examples

2 documented examples

Usage

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.

  • 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.
  • Expect input chrome or selected-value rendering. BaseTypeahead is an engine; the caller owns those visible parts.
  • Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.
  • Treat Escape as cancellation of pending source work. It hides the current popup, but a late response can reopen it.

Typed props

PropType and behavior
searchSourceSearchSource<T> · required
Data source providing search and bootstrap methods.
valueT | null · required
Currently selected item.
onChange(item: T | null) => void · required
Called when the selection changes.
renderItem(item: T) => ReactNode
Custom render function for dropdown items.
placeholderstring · default 'Search…'
Input placeholder text.
hasEntriesOnFocusboolean · default false
Show bootstrap results on focus before typing.
maxMenuItemsnumber · default 10
Maximum dropdown items to display.
menuWidthnumber
Requested dropdown width in pixels before viewport clamping.
minQueryLengthnumber · default 1
Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.
emptySearchResultsTextstring · default 'No results found'
Text shown when search returns no results.
isDisabledboolean · default false
Whether the input is disabled.
isFocusableDisabledboolean · default false
Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, but when applied after results are already open, Enter can still select the highlighted option.
hasAutoFocusboolean · default false
Auto-focus the input on mount.
debounceMsnumber · default 150
Debounce delay in ms before triggering search. Set to 0 for synchronous sources.
size'sm' | 'md' | 'lg' · default 'md'
Size used to scale dropdown option padding.
anchorRefRefObject<HTMLElement | null>
Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.
inputXStyleStyleXStyles
Additional StyleX styles for the input element.
xstyleStyleXStyles
Standard BaseProps StyleX styles applied to the input. Must be a stylex.create() value, not an inline style object.
inputTabIndexnumber
Legacy input-specific alias for native tabIndex. When provided, it takes precedence; otherwise native tabIndex is preserved.
onKeyDown(e: React.KeyboardEvent<HTMLInputElement>) => void
Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.
onChangeQuery(query: string) => void
Callback fired when the search query text changes.
onOpenChange(isOpen: boolean) => void
Callback when the dropdown opens or closes.
inputIdstring
Legacy input-specific alias for native id. When provided, it takes precedence; otherwise native id is preserved.
ariaDescribedBystring
Legacy input-specific alias for native aria-describedby. When provided, it takes precedence; otherwise the native attribute is preserved.
ariaLabelledBystring
Legacy input-specific alias for native aria-labelledby. When provided, it takes precedence; otherwise the native attribute is preserved.

Anatomy

Input · required

Bare combobox input. The caller supplies its visible field chrome and accessible name.

Loading status · optional

Named Spinner shown beside the input while an asynchronous source is pending, unless a composed owner takes over the busy indicator lane.

Dropdown · optional

Anchored listbox surface containing current search or bootstrap results.

Empty state · optional

Disabled listbox option shown after a completed search returns no results.

Result group heading · optional

Visible label for a group of result options.

Result row · optional

Option wrapper that owns highlight, selection, pointer, and keyboard behavior.

Default item content · optional

TypeaheadItem label and optional supporting content rendered inside a result row.

Caller-rendered item content · optional

Caller content supplied through renderItem or item.element inside the stable result row.

Selected result state · optional

Selected row weight and trailing check shown when a result matches value.