XDSBaseTypeahead@xds/core · Typeahead
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
Props
| Prop | Type | Description |
|---|---|---|
searchSourcerequired | XDSSearchSource<T> | Data source providing search and bootstrap methods. |
valuerequired | T | null | Currently selected item. |
onChangerequired | (item: T | null) => void | Called when the selection changes. |
renderItem | (item: T) => ReactNode | Custom render function for dropdown items. |
placeholder | string (default: 'Search...') | Input placeholder text. |
hasEntriesOnFocus | boolean (default: false) | Show bootstrap results on focus before typing. |
maxMenuItems | number (default: 10) | Maximum dropdown items to display. |
emptySearchResultsText | string (default: 'No results found') | Text shown when search returns no results. |
isDisabled | boolean (default: false) | Whether the input is disabled. |
hasAutoFocus | boolean (default: false) | Auto-focus the input on mount. |
debounceMs | number (default: 150) | Debounce delay in ms before triggering search. Set to 0 for synchronous sources. |
anchorRef | RefObject<HTMLElement | null> | Ref to the anchor element for dropdown positioning. If not provided, the input itself is used. |
inputXStyle | StyleXStyles | Additional StyleX styles for the input element. |
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. |
inputId | string | ID for the input element (for label association). |
ariaDescribedBy | string | Additional aria-describedby IDs. |