Combobox

Installation

Bash

pnpm dlx shadcn@latest add @spaceui/primitives-combobox

pnpm dlx shadcn@latest add @spaceui/primitives-combobox

Usage

Single Selection

Code

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from '@/components/ui/combobox'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items}>
  <ComboboxInput placeholder="Select an item..." />
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Anatomy

Code

<Combobox>
  <ComboboxInput />
  <ComboboxPopup>
    <ComboboxList>
      <ComboboxItem />
      <ComboboxEmpty />
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Multiple Selection

Code

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
} from '@/components/ui/combobox'

const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(value: { value: string; label: string }[]) => (
        <>
          {value?.map((item) => (
            <ComboboxChip key={item.value} aria-label={item.value}>
              {item.label}
            </ComboboxChip>
          ))}
          <ComboboxChipsInput
            placeholder={value.length > 0 ? undefined : "Select an item..."}
            aria-label="Select an item"
          />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Features

Sizes

Combobox inputs in sm, default, and lg sizes.

Accessibility

Follows the WAI-ARIA Combobox Pattern.
Search input controls list focus via aria-activedescendant.

Keyboard Interactions

Key	Action
`ArrowDown`	Moves focus to the next matching suggestion.
`ArrowUp`	Moves focus to the previous matching suggestion.
`Enter`	Confirms the currently highlighted suggestion.
`Escape`	Closes the suggestion list popup.

API Reference

Combobox

The root combobox component. Manages the combobox state and provides context to child components.

Prop	Type	Description
`items`	readonly unknown[]	The array of items to display in the combobox
`multiple`	boolean	Whether to allow multiple selection
`open`	boolean	Controls whether the popup is open
`...props`	React.ComponentProps<typeof Combobox>	All Base UI Combobox props are supported

ComboboxInput

The input field component for single selection mode with extended features for size variants and addon support.

Prop	Type	Default	Description
`size`	sm\|default\|lg	default	The size variant of the input field
`startAddon`	React.ReactNode	-	Element to display at the start (left side) of the input, such as an icon
`showTrigger`	boolean	true	Whether to display a trigger button (chevron icon) on the right side of the input
`showClear`	boolean	false	Whether to display a clear button (X icon) on the right side of the input when there is a value
`triggerProps`	Combobox.Trigger.Props	-	Props forwarded to the internal trigger button, useful for overriding `aria-label`
`clearProps`	Combobox.Clear.Props	-	Props forwarded to the internal clear button, useful for overriding `aria-label`
`className`	string	-	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Input props	-	All standard combobox input attributes are supported

ComboboxPopup

The popup container that displays the combobox options.

Prop	Type	Default	Description
`side`	top\|bottom\|left\|right	bottom	Preferred edge to position the popup relative to the trigger/input
`sideOffset`	number	4	Distance from the trigger in pixels
`align`	start\|center\|end	center	Alignment relative to the trigger along the cross-axis
`alignOffset`	number	0	Distance in pixels to shift the popup along the alignment axis
`anchor`	Element\|null\|React.RefObject<Element>	-	Custom anchor element or ref to anchor the popup against
`portalProps`	Combobox.Portal.Props	-	Props forwarded to the internal portal (`keepMounted`, `container`, etc.); see Base UI Combobox portal API
`className`	string	-	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Popup props	-	All standard combobox popup attributes are supported

ComboboxList

A scrollable container for combobox items.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox List props	All standard combobox list attributes are supported

ComboboxItem

An individual selectable combobox item.

Prop	Type	Description
`value`	unknown	The value of the item
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Item props	All standard combobox item attributes are supported

ComboboxEmpty

Displays a message when no results are found.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Empty props	All standard combobox empty attributes are supported

ComboboxGroup

Groups related combobox items together.

Prop	Type	Description
`items`	readonly unknown[]	The array of items in this group
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Group props	All standard combobox group attributes are supported

ComboboxGroupLabel

Displays a label for a combobox group.

Prop	Type	Description
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Group Label props	All standard combobox group label attributes are supported

ComboboxCollection

Used to wrap items within a group for rendering.

Prop	Type	Description
`...props`	Base UI Combobox Collection props	All standard combobox collection attributes are supported

ComboboxChips

Container for displaying selected chips in multiple selection mode.

Prop	Type	Description
`startAddon`	React.ReactNode	Element to display at the start (left side) of the chips area
`className`	string	Additional CSS classes to apply to the component
`...props`	React.ComponentProps<'div'>	All standard div attributes are supported

ComboboxChipsInput

The input field component for use inside ComboboxChips in multiple selection mode. This is a minimal input without the wrapper, trigger, or clear button.

Prop	Type	Default	Description
`size`	sm\|default\|lg	default	The size variant of the input field
`className`	string	-	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Input props	-	All standard combobox input attributes are supported

ComboboxChip

An individual chip representing a selected item in multiple selection mode.

Prop	Type	Description
`removeProps`	Combobox.ChipRemove.Props	Props forwarded to the internal remove button, useful for overriding `aria-label`
`className`	string	Additional CSS classes to apply to the component
`...props`	Base UI Combobox Chip props	All standard combobox chip attributes are supported

ComboboxValue

Provides access to the current value for custom rendering.

Prop	Type	Description
`...props`	Base UI Combobox Value props	All standard combobox value attributes are supported

Examples

Large combobox

Combobox with label

Fruits

Combobox auto highlighting the first option

Combobox with clear button

Combobox with grouped items

Combobox with multiple selection

Apple

Strawberry

Combobox form

Combobox multiple form

Combobox with start addon

Combobox multiple with start addon

Apple

Grape

Pill-shaped combobox

Timezone combobox

Timezone combobox with search input

Combobox with select trigger

Combobox multiple with stacked chips

JHJenny HamiltonHighest200%
PSPaul SmithMedium100%

Combobox multiple with stacked divided chips

JHJenny HamiltonHighest200%
PSPaul SmithMedium100%