Autocomplete

Typeahead input that filters suggestions as you search.

Installation

npx shadcn@latest add @iconiq/b-autocomplete

Props

Autocomplete

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"

Default true

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

Default false

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.

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

Styled input shell with border, focus ring, and optional clear control. The suggestion panel opens while typing, not on focus or click.

labelReact.ReactNode

Optional field label rendered above the input and linked with htmlFor.

labelClassNamestring

Optional class names merged onto the field label.

placeholderstring

Shown when the input is empty.

showClearboolean

Default true

Controls whether AutocompleteClear is rendered.

showTriggerboolean

Default false

When true, renders a chevron trigger that toggles the suggestion panel.

disabledboolean

Default false

Disables the input and clear button.

AutocompleteContent

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

Default 6

Distance between the input and the popup.

AutocompleteList

Scrollable suggestion list rendered inside AutocompleteContent.

childrenReactNode | ((item, index) => ReactNode)

Required

Render explicit AutocompleteItem children or a render function when using the root items prop.

classNamestring

Merged with the default list spacing and scroll classes.

AutocompleteItem

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.

Registry bundle

Install the exact registry entry shown on the right when you want the component file and its declared runtime dependencies together.

Dependencies: @base-ui/react, motion, lucide-react.

This page documents the Base UI install only. Radix UI does not ship a dedicated autocomplete primitive.

The generated registry file is /r/b-autocomplete.json.