iconiq
—Open GitHub

Autocomplete

Typeahead input that filters suggestions as you search.

Installation

npx shadcn@latest add @iconiq/b-autocomplete

ReducedMotion

Pass reducedMotionwhen you want the installed component to settle into its quieter motion path immediately. Leaving the prop unset still respects the user's system-level reduced motion preference.

Props

Autocomplete

12 props

Root autocomplete controller. Compose AutocompleteInput, AutocompleteContent, AutocompleteList, and AutocompleteItem inside it.
itemsreadonly Item[]
Item collection used for list filtering. Pass a flat array or grouped items for sectioned results.
valuestring
Controlled input text shown in the field.
defaultValuestring
Initial input text for uncontrolled usage.
onValueChange(value: string) => void
Called when the input text changes from typing or when a suggestion is accepted.
itemToStringValue(item: Item) => string
Maps each item to the string used for filtering and the committed input value.
mode"list" | "both" | "inline" | "none"
Default"list"
Controls filtering and inline completion while navigating suggestions.
autoHighlightboolean | "always"
Defaulttrue
Automatically highlights the first matching item while typing.
openboolean
Controlled popup state. Pair with onOpenChange.
onOpenChange(open: boolean, eventDetails) => void
Called when the suggestion panel opens or closes. Use with open for controlled popup state.
openOnInputClickboolean
Defaultfalse
When true, clicking the input opens the suggestion panel even before typing.
isItemEqualToValue(item: Item, value: Item) => boolean
Custom equality for object items. Use when items are recreated on each render.
reducedMotionboolean
Forces the Iconiq motion layer into reduced-motion mode.

Notes

Built on Base UI Autocomplete with list filtering, keyboard navigation, and a sliding highlight treatment.
Radix UI does not ship a dedicated autocomplete primitive, so this install is Base UI only.
Pass value and onValueChange for controlled input text. The popup opens while typing by default, not on focus.
Object items require itemToStringValue. Use isItemEqualToValue if selection highlight behaves incorrectly.

AutocompleteInput

4 props

Styled input shell with border, focus ring, and optional clear control. The suggestion panel opens while typing, not on focus or click.
placeholderstring
Shown when the input is empty.
showClearboolean
Defaulttrue
Controls whether AutocompleteClear is rendered.
showTriggerboolean
Defaultfalse
When true, renders a chevron trigger that toggles the suggestion panel.
disabledboolean
Defaultfalse
Disables the input and clear button.

AutocompleteContent

2 props

Portaled suggestion panel with a subtle fade-slide entrance and anchored width.
side"top" | "right" | "bottom" | "left"
Default"bottom"
Preferred side for the popup.
sideOffsetnumber
Default6
Distance between the input and the popup.

AutocompleteItem

2 props

Suggestion row with optional description and a spring-driven highlight fill.
valueItem
Required
Item value passed to Base UI for selection handling.
descriptionReactNode
Optional secondary line below the primary label.