Combobox - Saturation UI

Installation

pnpm dlx shadcn@latest add @saturation-ui/combobox

Tailwind v4 — Source Scanning

The public shadcn registry installs component source into your project. If Tailwind v4 isn't scanning your components directory, add this to your CSS entry file:

@source "../components";

This ensures all utility classes in CVA variants and data attribute selectors are included in your build.

Usage

import { Combobox } from "@/components/ui/combobox"

<Combobox
  options={[
    { value: "apple", label: "Apple" },
    { value: "banana", label: "Banana" },
  ]}
  value={value}
  onValueChange={(next) => setValue(next as string)}
  placeholder="Select a fruit..."
/>

Examples

With Status

Combobox with status indicators.

With Icon

Combobox with icons.

With User

User selection with avatars.

With Groups

Grouped options.

Multiple

Multiple selection.

API Reference

Prop	Type	Default	Description
`options`*	`ComboboxOption[]`	—	Available options. Each has { value, label, description? }.
`value`*	`string \| string[]`	—	Selected value(s). String for single-select, string[] for multi-select.
`onValueChange`*	`(value: string \| string[]) => void`	—	Called when selection changes.
`multiple`	`boolean`	`false`	Enable multi-select mode.
`onSearch`	`(query: string) => void`	—	Controlled search — disables cmdk's built-in filtering. Caller updates options in response.
`placeholder`	`string`	`"Select..."`	Trigger placeholder when nothing is selected.
`searchPlaceholder`	`string`	`"Search..."`	Search input placeholder.
`emptyMessage`	`string`	`"No results."`	Message shown when no options match.
`disabled`	`boolean`	`false`	Disable the trigger.
`loading`	`boolean`	`false`	Show loading indicator in the popover.
`loadingText`	`string`	`"Loading..."`	Text shown while loading.
`variant`	`"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "glass" \| "link"`	`"secondary"`	Trigger button variant — override for different surface contexts.
`renderOption`	`(option, isSelected) => ReactNode`	—	Custom option renderer.
`resolveLabel`	`(value: string) => string \| null`	—	Resolve a value to a display label (for selected items not in current options).
`align`	`"start" \| "center" \| "end"`	`"start"`	Popover alignment.
`portalContainer`	`HTMLElement \| null`	—	DOM element to portal the popover into (useful inside Dialog).