Skip to content
CraftDocs
GitHub
Home
Home
Changelog
What's New
Guide
Guide
Getting Started
Principles
Styling Components
Theme System
Foundations
All Tokens
Color
Elevation
Icons
Motion
Shape
Spacing
Typography
Libraries
Libraries
@xds/cli
@xds/core
Themes
Themes
Theme: daily
Default Theme
Theme: matcha
Neutral Theme
Components
Components
AppShell
AspectRatio
Avatar
Avatar
AvatarStatusDot
Badge
Banner
Breadcrumbs
BreadcrumbItem
Breadcrumbs
Button
Button
IconButton
ToggleButton
ToggleButtonGroup
Calendar
Card
Carousel
Chat
ChatComposer
ChatComposerDrawer
ChatComposerInput
ChatComposerTokenElement
ChatDictationButton
ChatLayout
ChatLayoutScrollButton
ChatMessage
ChatMessageBubble
ChatMessageList
ChatMessageMetadata
ChatSendButton
ChatSystemMessage
ChatTokenizedText
ChatToolCalls
Checkbox
CheckboxInput
CheckboxList
CheckboxListItem
ClickableCard
Code
CodeBlock
Collapsible
Collapsible
CollapsibleGroup
useXDSCollapsible
CommandPalette
CommandPalette
CommandPaletteEmpty
CommandPaletteFooter
CommandPaletteGroup
CommandPaletteInput
CommandPaletteItem
CommandPaletteList
DateInput
Dialog
AlertDialog
Dialog
DialogHeader
useXDSImperativeAlertDialog
useXDSImperativeDialog
Divider
DropdownMenu
DropdownMenu
DropdownMenuDivider
DropdownMenuItem
DropdownMenuItemData
DropdownMenuSection
EmptyState
Field
Field
FieldLabel
FieldStatus
Heading
HoverCard
Icon
Kbd
Layout
Center
FormLayout
Grid
GridSpan
HStack
Layout
LayoutContainer
LayoutContent
LayoutFooter
LayoutHeader
LayoutPanel
Section
StackItem
VStack
Link
List
List
ListItem
Markdown
MetadataList
MetadataList
MetadataListItem
MobileNav
MoreMenu
NavHeadingMenu
NavIcon
NumberInput
OverflowList
Pagination
Popover
PowerSearch
ProgressBar
Radio
RadioList
RadioListItem
Resizable
ResizeHandle
useXDSResizable
SegmentedControl
SegmentedControl
SegmentedControlItem
SelectableCard
Selector
MultiSelector
Selector
SelectorOption
SideNav
SideNav
SideNavCollapseButton
SideNavHeading
SideNavItem
SideNavSection
Skeleton
Slider
Spinner
StatusDot
Switch
Table
BaseTable
Table
TableCell
TableHeaderCell
TableRow
useXDSTableColumnSettings
useXDSTablePagination
useXDSTableSelection
useXDSTableSelectionState
useXDSTableSortable
Tabs
Tab
TabList
TabMenu
Text
TextArea
TextInput
Thumbnail
TimeInput
Timestamp
Toast
Toast
useXDSToast
Token
Tokenizer
Toolbar
Tooltip
TopNav
TopNav
TopNavHeading
TopNavItem
TopNavMegaMenu
TopNavMegaMenuFeaturedCard
TopNavMegaMenuItem
TopNavMenu
TreeList
Typeahead
BaseTypeahead
Typeahead
TypeaheadItem
useXDSHoverCard
useXDSPopover
useXDSTooltip
Utilities
Utilities
LinkProvider
MediaTheme
SyntaxTheme
Theme
useClickableContainer
useEntryAnimation
useFocusTrap
useGridFocus
useImageMode
useInputContainer
useListFocus
useMediaQuery
useOverflow
useScrollLock
useScrollOverflow
useXDSLayer
useXDSStreamingText
Terms of UsePrivacy Policy
Type to search
↑↓Navigate↵SelectEscClose
Typeahead@xds/core · XDSTypeahead v0.0.13

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.
ts
import {XDSTypeahead} from '@xds/core/Typeahead'

Best practices

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

Sub-components

Typeahead is a compound component with 3 sub-components.

XDSBaseTypeahead

Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.
PropTypeDescription
searchSourcerequired
XDSSearchSource<T>Data source providing search and bootstrap methods.
valuerequired
T | nullCurrently selected item.
onChangerequired
(item: T | null) => voidCalled when the selection changes.
renderItem
(item: T) => ReactNodeCustom 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
StyleXStylesAdditional StyleX styles for the input element.
onKeyDown
(e: React.KeyboardEvent<HTMLInputElement>) => voidAdditional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.
onChangeQuery
(query: string) => voidCallback fired when the search query text changes.
onOpenChange
(isOpen: boolean) => voidCallback when the dropdown opens or closes.
inputId
stringID for the input element (for label association).
ariaDescribedBy
stringAdditional aria-describedby IDs.

XDSTypeahead

Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.
PropTypeDescription
labelrequired
stringAccessible label for the input.
searchSourcerequired
XDSSearchSource<T>Data source providing search and bootstrap methods for populating the dropdown.
valuerequired
T | nullCurrently selected item, or null if nothing is selected.
onChangerequired
(item: T | null) => voidCalled when the selection changes.
placeholder
stringInput placeholder text.
hasEntriesOnFocus
boolean (default: false)Show bootstrap results on focus before typing.
hasClear
boolean (default: true)Show clear button to deselect the current value.
isDisabled
boolean (default: false)Disables the input.
maxMenuItems
number (default: 10)Maximum number of dropdown items to display.
status
XDSInputStatusValidation status object with type and message for error/warning/success states.
renderItem
(item: T) => ReactNodeCustom render function for dropdown items. Default renders XDSTypeaheadItem.
isLabelHidden
boolean (default: false)Visually hides the label while keeping it accessible.
description
stringHelper text displayed below the label.
isRequired
boolean (default: false)Marks the field as required.
isOptional
boolean (default: false)Shows an optional indicator on the label.
labelTooltip
stringTooltip text shown on the label.
emptySearchResultsText
string (default: 'No results found')Text shown when search returns no results.
hasAutoFocus
boolean (default: false)Auto-focus the input on mount.
size
'sm' | 'md' (default: 'md')Input and token size.
debounceMs
number (default: 150)Debounce delay in ms before triggering search. Set to 0 for synchronous sources.
onChangeQuery
(query: string) => voidCallback fired when the search query text changes.
onOpenChange
(isOpen: boolean) => voidCallback when the dropdown opens or closes.
xstyle
StyleXStylesStyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSTypeaheadItem

Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.
PropTypeDescription
itemrequired
XDSSearchableItemThe search result item to render.
icon
ReactNodeIcon or avatar to display before the label.
description
stringDescription text displayed below the label.
isDisabled
boolean (default: false)Whether this item is visually disabled.
group
stringGroup label for grouping items visually.

Examples

Common configurations, variations, and states.
Typeahead — Limited ResultsTypeahead with a capped dropdown showing at most three results.
tsx
'use client';
​
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
import {XDSCenter} from '@xds/core/Center';
​
const items: XDSSearchableItem[] = [
{id: '1', label: 'United States'},
{id: '2', label: 'United Kingdom'},
{id: '3', label: 'Canada'},
{id: '4', label: 'Australia'},
{id: '5', label: 'Germany'},
{id: '6', label: 'France'},
{id: '7', label: 'Japan'},
{id: '8', label: 'Brazil'},
];
​
const searchSource: XDSSearchSource = {
search: (query: string) =>
items.filter(i => i.label.toLowerCase().includes(query.toLowerCase())),
bootstrap: () => items.slice(0, 5),
};
​
export default function TypeaheadLimitedResults() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
<XDSCenter width={320}>
<XDSTypeahead
label="Country"
placeholder="Search countries..."
searchSource={searchSource}
value={value}
onChange={setValue}
hasEntriesOnFocus
maxMenuItems={3}
/>
</XDSCenter>
);
}
Typeahead — Search FieldSearch input with icon and suggestions on focus.
tsx
'use client';
​
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
import {XDSCenter} from '@xds/core/Center';
import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
​
const items: XDSSearchableItem[] = [
{id: '1', label: 'Olivia Martin'},
{id: '2', label: 'Jackson Lee'},
{id: '3', label: 'Isabella Nguyen'},
{id: '4', label: 'William Kim'},
{id: '5', label: 'Sofia Davis'},
{id: '6', label: 'Lucas Brown'},
{id: '7', label: 'Mia Wilson'},
{id: '8', label: 'Ethan Jones'},
];
​
const searchSource: XDSSearchSource = {
search: (query: string) =>
items.filter(i => i.label.toLowerCase().includes(query.toLowerCase())),
bootstrap: () => items.slice(0, 5),
};
​
export default function TypeaheadSearchField() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
<XDSCenter width={320}>
<XDSTypeahead
label="Team member"
placeholder="Search people..."
searchSource={searchSource}
value={value}
onChange={setValue}
startIcon={MagnifyingGlassIcon}
hasEntriesOnFocus
/>
</XDSCenter>
);
}
Typeahead — With Helper TextTypeahead with a description below the label.
tsx
'use client';
​
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
import {XDSCenter} from '@xds/core/Center';
​
const items: XDSSearchableItem[] = [
{id: '1', label: 'Engineering'},
{id: '2', label: 'Design'},
{id: '3', label: 'Marketing'},
{id: '4', label: 'Sales'},
{id: '5', label: 'Product'},
{id: '6', label: 'Finance'},
{id: '7', label: 'Legal'},
{id: '8', label: 'Operations'},
];
​
const searchSource: XDSSearchSource = {
search: (query: string) =>
items.filter(i => i.label.toLowerCase().includes(query.toLowerCase())),
bootstrap: () => items.slice(0, 5),
};
​
export default function TypeaheadWithHelperText() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
<XDSCenter width={320}>
<XDSTypeahead
label="Department"
placeholder="Search departments..."
searchSource={searchSource}
value={value}
onChange={setValue}
description="Select the department this request should be routed to"
/>
</XDSCenter>
);
}
Typeahead — With ValidationTypeahead with an error validation message.
tsx
'use client';
​
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
import {XDSCenter} from '@xds/core/Center';
​
const items: XDSSearchableItem[] = [
{id: '1', label: 'New York'},
{id: '2', label: 'San Francisco'},
{id: '3', label: 'London'},
{id: '4', label: 'Berlin'},
{id: '5', label: 'Tokyo'},
{id: '6', label: 'Singapore'},
{id: '7', label: 'Sydney'},
{id: '8', label: 'Toronto'},
];
​
const searchSource: XDSSearchSource = {
search: (query: string) =>
items.filter(i => i.label.toLowerCase().includes(query.toLowerCase())),
bootstrap: () => items.slice(0, 5),
};
​
export default function TypeaheadWithValidation() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
<XDSCenter width={320}>
<XDSTypeahead
label="Office"
placeholder="Search offices..."
searchSource={searchSource}
value={value}
onChange={setValue}
status={{type: 'error', message: 'Please select an office location'}}
/>
</XDSCenter>
);
}

Showcase source

tsx
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
​
const fruits: XDSSearchableItem[] = [
{id: '1', label: 'Apple'},
{id: '2', label: 'Banana'},
{id: '3', label: 'Cherry'},
{id: '4', label: 'Date'},
{id: '5', label: 'Elderberry'},
{id: '6', label: 'Fig'},
{id: '7', label: 'Grape'},
{id: '8', label: 'Honeydew'},
];
​
const fruitSource: XDSSearchSource = {
search: (query: string) =>
fruits.filter(f => f.label.toLowerCase().includes(query.toLowerCase())),
bootstrap: () => fruits.slice(0, 5),
};
​
export default function TypeaheadShowcase() {
return (
<div style={{width: 320}}>
<XDSTypeahead
label="Fruit"
placeholder="Search fruits..."
searchSource={fruitSource}
value={null}
onChange={() => {}}
/>
</div>
);
}