iconiq
—Open GitHub

Combobox

Searchable single-select input with inline filtering, arrow-key navigation, and an animated dropdown that stays visually attached to the field.

Open in

Installation

npx shadcn@latest add @iconiq/combobox

Props

ComboboxOption

3 props

Each selectable row is described by a plain object and can optionally include a secondary description line.
valuestring
Required
Stable identifier used for the selected state and returned through onChange.
labelstring
Required
Primary text shown in the closed field and inside the dropdown row.
descriptionstring
Optional helper copy rendered under the label inside the dropdown list.

Combobox

8 props

Searchable single-select field that owns open state, search query, and active row internally, while the selected value stays parent-driven.
optionsComboboxOption[]
Required
Available rows rendered in display order and used as the filtering source.
valuestring
Currently selected option value. The component derives the visible label entirely from this prop when the field is closed.
onChange(value: string) => void
Called when a row is selected and also when the clear action resets the field to an empty string.
placeholderstring
Default"Select an option..."
Shown when no value is selected, and again while the field is open with an empty query.
emptyMessagestring
Default"No results found."
Fallback copy rendered when filtering produces no matching options.
classNamestring
Merged onto the outer relative wrapper so width or placement can be adjusted externally.
disabledboolean
Defaultfalse
Disables the input, blocks opening, and applies a reduced-opacity presentation.
clearableboolean
Defaulttrue
Controls whether the clear button appears once a value has been selected.

Notes

This is effectively controlled for selection. If the parent does not feed the next onChange result back into value, the checkmark and closed-field label do not update.
Closing the popover resets the live query string, so reopening the field starts from the full option list again.