Combobox

Forms

An input combined with a filterable list of predefined options.

Comboboxes pair free text entry with a pick list. Type to filter the items, click or press Enter to select, and use the checkmark to confirm the current choice.

npx shadcn@latest add combobox

Basic usage

Items are filtered as you type. The selected value is controlled by the parent.

Preview

Live

Selected: none

tsx

1type Framework = { label: string; value: string }
2
3const frameworks: Framework[] = [
4  { label: "React", value: "react" },
5  { label: "Vue", value: "vue" },
6  { label: "Svelte", value: "svelte" },
7  { label: "Angular", value: "angular" },
8]
9
10<Combobox<Framework>
11  items={frameworks}
12  value={value}
13  onValueChange={setValue}
14>
15  <ComboboxInput placeholder="Pick a framework…" />
16  <ComboboxPopup>
17    {(framework) => (
18      <ComboboxItem value={framework}>
19        {framework.label}
20      </ComboboxItem>
21    )}
22  </ComboboxPopup>
23</Combobox>

Rendering the value

The combobox keeps the selected value; you choose how to display it.

Preview

Live

Selected: none

tsx

1<p>
2  Selected: {value ? value.label : "none"}
3</p>

API reference

All props of the underlying Base UI primitive are forwarded. The table below documents the Shelf-specific props.

Prop	Type	Description
items	T[]	The items to filter and display in the popup.
value	T \| null	The controlled selected value.
onValueChange	(value: T \| null) => void	Called when the selection changes.
defaultValue	T \| null	The uncontrolled initial selection.
openOnInputClick	boolean= true	Opens the popup when the input is clicked.
placeholder	string	On ComboboxInput, shown while empty.