Combobox

Combobox is built on the Base UI Combobox. The Combobox root takes the items to choose from and holds the value. ComboboxInput renders the text field inside an InputGroup, with an optional button that opens the list and an optional clear button. ComboboxContent renders the popup in a portal; inside it, ComboboxList renders each item through a render function, ComboboxEmpty appears when nothing matches, and ComboboxItem shows a check mark when selected. Group related items with ComboboxGroup, ComboboxLabel, ComboboxCollection and ComboboxSeparator.

For multiple selection, replace ComboboxInput with ComboboxChips, which shows each selected value as a ComboboxChip next to a ComboboxChipsInput. Use a combobox when the list is long enough that typing to filter helps. For a short, fixed list without filtering, use a select; for a list of actions rather than values, use a command menu.

Installation

CLI

$ pnpm dlx shadcn@latest add @esuiss/combobox

Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add combobox

Manual

Install the dependencies and add the cn helper:

$ pnpm add @base-ui/react @phosphor-icons/react

Add the pieces it builds on: Button, Input Group.
Copy the source into components/ui/combobox.tsx:

Update the import paths to match your project.

Usage

import { ComboboxValue, ComboboxTrigger, ComboboxInput, ComboboxContent, ComboboxList, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxCollection, ComboboxEmpty, ComboboxSeparator, ComboboxChips, ComboboxChip, ComboboxChipsInput }

<div

Pass items to the root and a function as the child of ComboboxList, which receives each item and returns a ComboboxItem with a matching value. The value is uncontrolled with defaultValue, or controlled with value and onValueChange. To read or control the typed text, use inputValue and onInputValueChange.

For grouped data, pass groups as items, render a ComboboxGroup with its own items for each one, and render its items with ComboboxCollection. For multiple selection, set multiple on the root, create a ref with useComboboxAnchor, attach it to ComboboxChips, and pass it as anchor to ComboboxContent so the popup aligns to the chips field. Use ComboboxValue with a render function to map the selected values to chips.

Examples

With clear button

A combobox with a starting value and a clear button, enabled with showClear.

Disabled

A disabled combobox whose input and toggle button cannot be focused or used.

Grouped

Options grouped by region with labels and separators between groups.

Highlight match

A controlled inputValue used to emphasize the matching part of each option.

Multiple

Multiple selection shown as removable chips, with Backspace removing the last chip.

API Reference

Anatomy11 parts

Combobox

The root that holds the items, the selected value and the open state.

Also accepts the props of ComboboxPrimitive.Root.

ComboboxValue

Renders the current value, or passes it to a render function, for example to draw chips.

Also accepts the props of ComboboxPrimitive.Value.Props.

ComboboxTrigger

A button that opens the list, with a caret icon.

Also accepts the props of ComboboxPrimitive.Trigger.Props.

ComboboxInput

The text field, rendered inside an InputGroup with optional open and clear buttons.

Prop	Type	Default	Description
`showTrigger`	`boolean`	`true`	Shows the button at the end of the field that opens the list.
`showClear`	`boolean`	`false`	Shows a clear button at the end of the field. When shown, it hides the open button.

Also accepts the props of ComboboxPrimitive.Input.Props.

ComboboxContent

The popup, rendered in a portal and positioned below the input.

Also accepts the props of ComboboxPrimitive.Popup.Props, ComboboxPrimitive.Positioner.Props.

ComboboxList

The scrollable list that renders items through a render function.

Also accepts the props of ComboboxPrimitive.List.Props.

ComboboxItem

A selectable option that shows a check mark when selected.

Also accepts the props of ComboboxPrimitive.Item.Props.

ComboboxGroup

Groups related options and takes its own items.

Also accepts the props of ComboboxPrimitive.Group.Props.

ComboboxLabel

The visible label of a group.

Also accepts the props of ComboboxPrimitive.GroupLabel.Props.

ComboboxCollection

Renders the items of a group through a render function.

Also accepts the props of ComboboxPrimitive.Collection.Props.

ComboboxEmpty

Content shown when no options match the typed text.

Also accepts the props of ComboboxPrimitive.Empty.Props.

ComboboxSeparator

A divider between groups.

Also accepts the props of ComboboxPrimitive.Separator.Props.

ComboboxChips

The field that holds selected values as chips in multiple selection.

Also accepts the props of React.ComponentPropsWithRef<typeof ComboboxPrimitive.Chips>, ComboboxPrimitive.Chips.Props.

ComboboxChip

A selected value shown as a chip, with an optional remove button.

Prop	Type	Default	Description
`showRemove`	`boolean`	`true`	Shows a button inside the chip that removes the value.
`removeLabel`	`string`	`Remove {value}`	Accessible name of the remove button. Defaults to `Remove` followed by the chip text.

Also accepts the props of ComboboxPrimitive.Chip.Props.

ComboboxChipsInput

The text field placed after the chips in multiple selection.

Also accepts the props of ComboboxPrimitive.Input.Props.

Accessibility

The input has the combobox role and sets aria-expanded to reflect whether the list is open.
The popup has the listbox role, options have the option role and selected options set aria-selected; groups have the group role and take their name from ComboboxLabel.
Typing filters the options. Arrow keys move the highlight, Enter selects the highlighted option, and Escape closes the list.
In multiple selection, Backspace in the empty input removes the last chip.
The open button is labelled Show options and the clear button is labelled Clear.
When disabled, the input and the open button are disabled and removed from the Tab order.
Give the input an accessible name with a visible label or aria-label.

Notes

Styling hooks: data-slot values such as combobox-content, combobox-list, combobox-item, combobox-label, combobox-empty, combobox-chips, combobox-chip, combobox-chip-remove and combobox-chip-input.
Highlighted items get data-highlighted and disabled items get data-disabled.
The popup matches the width of its anchor through --anchor-width and limits its height to the available space.
Uses the popover, accent, primary, secondary and border colors.

Combobox pairs a text input with a floating list that filters its items as the user types. ComboboxInput draws the field with a caret trigger and an optional clear button, and ComboboxContent renders the list through a portal (inside a full-window overlay on iOS), positioned below the input and as wide as it.

For multiple selection, set multiple and use ComboboxChips with a ComboboxChip per selected value and a ComboboxChipsInput for typing. Each chip has a remove button.

Installation

$ pnpm dlx shadcn@latest add @esuiss-rn/combobox

See Installation for the components.json setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add combobox

$ pnpm dlx @esuiss/ui@latest add combobox --platform swift

Prop	Type	Default	Description
`items`	`Item[] \| ComboboxItemGroup<Item>[]`	-	The items to filter, flat or grouped.
`value`	`Value \| Value[] \| null`	-	The selected value, for controlled use.
`defaultValue`	`Value \| Value[] \| null`	-	The initial value when uncontrolled.
`onValueChange`	`(value, details) => void`	-	Called when the selection changes.
`multiple`	`boolean`	`false`	Allows several values to be selected.
`inputValue`	`string`	-	The typed text, for controlled use.
`onInputValueChange`	`(inputValue: string, details) => void`	-	Called when the typed text changes.
`filter`	`ComboboxFilter<Item> \| null`	-	Custom filter function; `null` turns filtering off.
`limit`	`number`	-	The maximum number of items shown.
`itemToStringLabel`	`(itemValue: Value) => string`	-	Returns the label shown for an item value.
`openOnInputClick`	`boolean`	`true`	Opens the list when the input is pressed.
`open`	`boolean`	-	Whether the list is open, for controlled use.
`defaultOpen`	`boolean`	`false`	Whether the list starts open when uncontrolled.
`onOpenChange`	`(open: boolean, details) => void`	-	Called when the list opens or closes.
`disabled`	`boolean`	`false`	Disables the combobox.
`readOnly`	`boolean`	`false`	Shows the value without allowing changes.

Prop	Type	Default	Description
`className`	`string`	-
`children`	`React.ReactNode`	-
`showTrigger`	`boolean`	`true`	Shows the caret button. Defaults to `true`.
`showClear`	`boolean`	`false`	Shows a clear button when there is text or a value.
`invalid`	`boolean`	-	Shows the destructive border; also read from a surrounding Field.

Installation

CLI

Manual

Usage

Examples

With clear button

Disabled

Grouped

Highlight match

Multiple

API Reference

Combobox

ComboboxValue

ComboboxTrigger

ComboboxInput

ComboboxContent

ComboboxList

ComboboxItem

ComboboxGroup

ComboboxLabel

ComboboxCollection

ComboboxEmpty

ComboboxSeparator

ComboboxChips

ComboboxChip

ComboboxChipsInput

Accessibility

Notes

Installation

Manual

Usage

Examples

Default

With value

With clear

Grouped

Multiple

With label

Disabled

Invalid

API Reference

Combobox

ComboboxTrigger

ComboboxInput

ComboboxContent

ComboboxList

ComboboxItem

ComboboxGroup

ComboboxLabel

ComboboxEmpty

ComboboxSeparator

ComboboxChips

ComboboxChip

ComboboxChipsInput

Accessibility

Notes