Combobox

Searchable input for filtering and choosing from a list.

Search, filter, and pick a route from one input.

Installation

npx shadcn@latest add @iconiq/b-combobox

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.

Search, filter, and pick a route from one input.

Props

Combobox

9 props

Root combobox controller. Compose ComboboxInput, ComboboxContent, ComboboxList, and ComboboxItem inside it.

itemsreadonly Item[]

Optional item collection used by Base UI for filtering and render-function lists.

valueItem | Item[] | null

Controlled selected value. Use an array when multiple is true.

defaultValueItem | Item[] | null

Initial selected value for uncontrolled usage.

onValueChange(value: Item | Item[] | null) => void

Called when an item is selected, a chip is removed, or the clear action resets the selection.

itemToStringLabel(item: Item) => string

Maps object values to the label shown in the input and used for text filtering.

itemToStringValue(item: Item) => string

Maps object values to the hidden form value.

inputValuestring

Controlled search text. Leave uncontrolled for Base UI to manage query state.

openboolean

Controlled popup state. Pair with onOpenChange.

reducedMotionboolean

Forces the Iconiq motion layer into reduced-motion mode.

Notes

The root wraps Base UI's combobox primitive in the same Iconiq reduced-motion config used by the previous wrapper.

Filtering, selection, typeahead, keyboard navigation, and clear behavior are delegated to Base UI while the visual treatment stays Iconiq.

ComboboxInput

5 props

Styled input shell with the previous border, focus ring, clear button, and rotating trigger icon.

placeholderstring

Shown when no item is selected and the input is empty.

showClearboolean

Defaulttrue

Controls whether ComboboxClear is rendered in the input.

showTriggerboolean

Defaulttrue

Controls whether the rotating trigger icon is rendered in the input.

classNamestring

Merged onto the input shell so width and local layout can be adjusted.

disabledboolean

Defaultfalse

Disables the input, clear button, and trigger while applying the previous reduced-opacity presentation.

ComboboxContent

4 props

Portaled dropdown surface with the previous white/dark panel, border, shadow, and fade-slide motion.

Default"bottom"

Preferred side for the popup.

align"start" | "center" | "end"

Default"start"

Popup alignment relative to the input anchor.

sideOffsetnumber

Default4

Gap between the input shell and dropdown.

classNamestring

Merged onto the animated popup panel.

Notes

The popup remains mounted while closing so the motion exit can complete before Base UI unmounts it.

The panel width matches the input anchor and the list scrolls at the same max height as before.

ComboboxList and ComboboxItem

3 props

Scrollable item list and animated rows with the previous active highlight, description layout, and selected checkmark spring.

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

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

ComboboxItem.valueItem

Stable value used by Base UI for selection.

ComboboxItem.descriptionReactNode

Optional secondary line rendered below the item label, matching the prior option description UI.

Notes

ComboboxEmpty, ComboboxGroup, ComboboxLabel, ComboboxSeparator, ComboboxCollection, and chip helpers are exported for larger compositions.

Keyboard navigation and filtering are handled by Base UI; the visual hover highlight and checkmark animation stay Iconiq.