Combobox

Searchable input for filtering and choosing from a list.

Installation

npx shadcn@latest add @iconiq/b-combobox

Props

Combobox

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.

The root wraps Base UI's combobox primitive with the same Iconiq motion layer 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

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

Default true

Controls whether ComboboxClear is rendered in the input.

showTriggerboolean

Default true

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

Default false

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

ComboboxContent

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

Default 4

Gap between the input shell and dropdown.

classNamestring

Merged onto the animated popup panel.

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

Scrollable item list rendered inside ComboboxContent with the previous max-height and motion treatment.

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

Required

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

classNamestring

Merged with the default list spacing and scroll classes.

ComboboxItem

Animated row with active highlight, optional description layout, and selected checkmark spring.

valueItem

Required

Stable value used by Base UI for selection.

childrenReactNode

Required

Primary item label content.

descriptionReactNode

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

classNamestring

Merged with the default row layout and motion classes.

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.

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, because Radix UI does not ship a dedicated combobox primitive.

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