Combobox

Basic

A production-ready searchable select / autocomplete built by composing Popover + Command primitives with Framer Motion animation. Supports single and multi-select, grouped options, custom rendering, and keyboard navigation.

<Comboboxoptions={[  { value: "react", label: "React" },  { value: "vue", label: "Vue" },  { value: "angular", label: "Angular" },  { value: "svelte", label: "Svelte" },  { value: "solid", label: "SolidJS" },]}placeholder="Select framework..."/>

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add combobox

pnpm dlx @work-rjkashyap/unified-ui add combobox

npx @work-rjkashyap/unified-ui add combobox

bunx @work-rjkashyap/unified-ui add combobox

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { Combobox } from "@work-rjkashyap/unified-ui";

Basic Usage

Pass an array of options with value and label fields. The component manages its own open/close and search state internally.

const frameworks = [
  { value: "react", label: "React" },
  { value: "vue", label: "Vue" },
  { value: "angular", label: "Angular" },
];

<Combobox options={frameworks} placeholder="Select framework..." />

Sizes

<Combobox options={options} placeholder="Small" size="sm" /><Combobox options={options} placeholder="Medium (default)" size="md" /><Combobox options={options} placeholder="Large" size="lg" />

Variants

<Combobox options={options} placeholder="Default variant" variant="default" /><Combobox options={options} placeholder="Primary variant" variant="primary" />

Multi-Select

Enable multi-select mode with the multi prop. Selected items appear as removable tags in the trigger.

<Comboboxmultioptions={[  { value: "react", label: "React" },  { value: "vue", label: "Vue" },  { value: "angular", label: "Angular" },  { value: "svelte", label: "Svelte" },  { value: "solid", label: "SolidJS" },  { value: "next", label: "Next.js" },]}placeholder="Select frameworks..."/>

Grouped Options

Organize options into visual groups using the group property on options and the groups prop for section labels.

<Comboboxgroups={[  { value: "frontend", label: "Frontend" },  { value: "backend", label: "Backend" },]}options={[  { value: "react", label: "React", group: "frontend" },  { value: "vue", label: "Vue", group: "frontend" },  { value: "node", label: "Node.js", group: "backend" },  { value: "python", label: "Python", group: "backend" },]}placeholder="Select technology..."/>

Option with Description and Icon

Options can include description text and a leading icon element for richer display.

<Combobox
  options={[
    {
      value: "react",
      label: "React",
      description: "A JavaScript library for building user interfaces",
      icon: <ReactIcon className="size-4" />,
    },
    {
      value: "vue",
      label: "Vue",
      description: "The progressive JavaScript framework",
      icon: <VueIcon className="size-4" />,
    },
  ]}
  placeholder="Select framework..."
/>

Disabled Options

Individual options can be disabled by setting disabled: true:

<Combobox
  options={[
    { value: "react", label: "React" },
    { value: "vue", label: "Vue", disabled: true },
    { value: "angular", label: "Angular" },
  ]}
  placeholder="Select..."
/>

Non-Searchable

Disable the search input to use the component as a styled select:

<Comboboxsearchable={false}options={[  { value: "low", label: "Low" },  { value: "medium", label: "Medium" },  { value: "high", label: "High" },  { value: "critical", label: "Critical" },]}placeholder="Select priority..."/>

Clearable

By default, a clear button appears when a value is selected. Set clearable={false} to disable it.

<Combobox options={options} placeholder="With clear (default)" /><Combobox options={options} placeholder="Without clear" clearable={false} />

Controlled

Use value and onSelect for single-select, or values and onMultiSelect for multi-select.

// Single
const [value, setValue] = useState<string | null>(null);

<Combobox
  options={options}
  value={value}
  onSelect={setValue}
  placeholder="Select..."
/>;

// Multi
const [values, setValues] = useState<string[]>([]);

<Combobox
  multi
  options={options}
  values={values}
  onMultiSelect={setValues}
  placeholder="Select..."
/>;

Custom Filter

Override the default case-insensitive label match with a custom filter function:

<Combobox
  options={options}
  filterOption={(option, query) =>
    option.label.toLowerCase().startsWith(query.toLowerCase())
  }
  placeholder="Starts-with filter..."
/>

Custom Rendering

Use renderOption to customize how each option is displayed, and renderValue to customize the trigger display:

<Combobox
  options={users}
  renderOption={(option, isSelected) => (
    <div className="flex items-center gap-2">
      <Avatar size="xs" src={option.icon} />
      <div>
        <p className="text-sm font-medium">{option.label}</p>
        <p className="text-xs text-muted-foreground">{option.description}</p>
      </div>
    </div>
  )}
  renderValue={(selected) =>
    selected ? (
      <div className="flex items-center gap-2">
        <Avatar size="xs" src={selected.icon} />
        <span>{selected.label}</span>
      </div>
    ) : null
  }
  placeholder="Select user..."
/>

In a Form

<FormField label="Assignee" description="Choose the team member to assign.">
  <Combobox
    options={teamMembers}
    value={assignee}
    onSelect={setAssignee}
    placeholder="Select assignee..."
  />
</FormField>

Props

ComboboxOption

ComboboxGroup

Motion

• Dropdown open/close — Uses the scaleIn preset (scale + opacity) via AnimatePresence for smooth enter/exit.
• Results list — Stagger animation with staggerContainerFast and slideUpSm per item for a cascading reveal.
• Empty state — Fades in with the fadeIn preset when no results match.
• Multi-select tags — Animate in/out with scale transitions on add/remove.
• All animations respect prefers-reduced-motion via useReducedMotion().

Keyboard Navigation

Accessibility

• The trigger uses role="combobox" with aria-expanded, aria-haspopup="listbox", and aria-controls.
• The dropdown uses role="listbox" with aria-label.
• Each option uses role="option" with aria-selected and aria-disabled.
• Active descendant tracking via aria-activedescendant.
• Disabled options are excluded from keyboard navigation.
• The search input is labeled with an aria-label.
• The clear button has aria-label="Clear selection".
• Multi-select tags have aria-label for their remove button.

Design Tokens