Combobox

Installation

pnpm dlx shadcn@latest add @paneui/combobox

Usage

import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList } from "@/components/ui/combobox"

<Combobox items={cities}>
  <ComboboxInput placeholder="Search cities" />
  <ComboboxContent>
    <ComboboxEmpty>No city found.</ComboboxEmpty>
    <ComboboxList>
      {(city: string) => (
        <ComboboxItem key={city} value={city}>
          {city}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Composition

Combobox
├── ComboboxInput            (or ComboboxTrigger > ComboboxValue)
└── ComboboxContent
    ├── ComboboxSearch       (with ComboboxTrigger)
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxGroup
            ├── ComboboxLabel
            ├── ComboboxCollection
            │   └── ComboboxItem
            └── ComboboxSeparator

Examples

Sizes

Input Options

Turn off controls a field doesn't need, like the clear button when a choice is required.

Controlled

Disabled

RTL

Keyboard

Typing filters the list; ArrowUp / ArrowDown move the highlight, Enter picks it and Escape closes the popup (standard combobox behaviour).

Multi Select is the same primitive in multiple mode, with chips.

API Reference

Built on the Combobox primitive. Only the props this library adds or changes are listed; everything else passes through.

Re-export of the primitive root, taking items, value, defaultValue, onValueChange, filter, disabled and its other props. Also accepts every prop of Combobox.Root.

ComboboxInput

Search input in an inset well with optional search icon, clear and chevron buttons. Also accepts every prop of Combobox.Input.

size= "default": "xs" | "sm" | "default" | "lg"; Height 24 / 28 / 32 / 36px. Defaults to the Combobox size, then a sized Field.
showSearchIcon= true: boolean; Show the leading search icon.
showClear= true: boolean; Render a clear button, shown once something is chosen.
showTrigger= true: boolean; Render the chevron that opens the list.

Prop	Type	Default	Description
size	"xs" \| "sm" \| "default" \| "lg"	"default"	Height 24 / 28 / 32 / 36px. Defaults to the `Combobox` size, then a sized `Field`.
showSearchIcon	boolean	true	Show the leading search icon.
showClear	boolean	true	Render a clear button, shown once something is chosen.
showTrigger	boolean	true	Render the chevron that opens the list.

data-size: On the input group, the size value.
data-disabled: On the input group while disabled.

Data attribute	Description
data-size	On the input group, the `size` value.
data-disabled	On the input group while disabled.

ComboboxTrigger

Raised button showing the chosen value, like SelectTrigger. Put ComboboxValue inside. Also accepts every prop of Combobox.Trigger.

size= "default": "xs" | "sm" | "default" | "lg"; Height 24 / 28 / 32 / 36px. Defaults to the Combobox size, then a sized Field.

Prop	Type	Default	Description
size	"xs" \| "sm" \| "default" \| "lg"	"default"	Height 24 / 28 / 32 / 36px. Defaults to the `Combobox` size, then a sized `Field`.

data-popup-open: Present while the list is open.

Data attribute	Description
data-popup-open	Present while the list is open.

ComboboxValue

Re-export. Renders the selected value, or placeholder when empty. Also accepts every prop of Combobox.Value.

ComboboxSearch

Search field styled for the top of the popup. Also accepts every prop of Combobox.Input.

ComboboxContent

Portal, positioner and popup in one. As wide as its anchor. Also accepts every prop of Combobox.Popup.

side= "bottom": "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"; Side of the anchor to place the popup on.
sideOffset= 6: number; Gap from the anchor in px.
align= "start": "start" | "center" | "end"; Alignment against the anchor.
anchor: Element | RefObject<Element> | VirtualElement | null; Position against another element.

Prop	Type	Default	Description
side	"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"	"bottom"	Side of the anchor to place the popup on.
sideOffset	number	6	Gap from the anchor in px.
align	"start" \| "center" \| "end"	"start"	Alignment against the anchor.
anchor	Element \| RefObject<Element> \| VirtualElement \| null	—	Position against another element.

ComboboxList

Scrollable list. Takes a render function called per item (or group). Also accepts every prop of Combobox.List.

ComboboxItem

Option row with a check indicator on the right when selected. Also accepts every prop of Combobox.Item.

data-highlighted: Present on the keyboard / pointer highlighted item.
data-disabled: Present when the item is disabled.

Data attribute	Description
data-highlighted	Present on the keyboard / pointer highlighted item.
data-disabled	Present when the item is disabled.

ComboboxGroup

Also accepts every prop of Combobox.Group.

ComboboxLabel

Also accepts every prop of Combobox.GroupLabel.

ComboboxSeparator

Also accepts every prop of Combobox.Separator.

ComboboxEmpty

Shown only when the filter leaves nothing to pick. Also accepts every prop of Combobox.Empty.

ComboboxCollection

Re-export. Renders a group's items with a render function. Also accepts every prop of Combobox.Collection.

useComboboxFilter

Re-export of Combobox.useFilter, returning locale-aware contains, startsWith and endsWith matchers for filter. Also accepts every prop of Combobox.useFilter.