Combobox

An autocomplete input with a filterable dropdown list, built on Base UI’s Combobox primitive.

Usage


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

Pass your items array to the items prop on Combobox and use a render function as the child of ComboboxList to render each item. This enables built-in filtering and the empty state.


const options = [
  { value: "option-1", label: "Option 1" },
  { value: "option-2", label: "Option 2" },
  { value: "option-3", label: "Option 3" },
]
 
<Combobox items={options}>
  <ComboboxInput placeholder="Select an option..." className="w-56" />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Examples

Multiple

Enable multiple selection with chips using the multiple prop. Control the selection with value and onValueChange, then render chips from your state array. Use useComboboxAnchor so the popup aligns to the chips container.


import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxChipsInput,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxItem,
  ComboboxList,
  useComboboxAnchor,
} from "@/components/ui/combobox"
 
const frameworks = [
  { value: "next.js", label: "Next.js" },
  { value: "remix", label: "Remix" },
]
 
export function MyCombobox() {
  const anchor = useComboboxAnchor()
  const [selected, setSelected] = React.useState<string[]>([])
 
  return (
    <Combobox multiple items={frameworks} value={selected} onValueChange={setSelected}>
      <ComboboxChips ref={anchor} className="w-72">
        {selected.map((v) => {
          const item = frameworks.find((f) => f.value === v)
          return <ComboboxChip key={v}>{item?.label ?? v}</ComboboxChip>
        })}
        <ComboboxChipsInput placeholder={selected.length === 0 ? "Select frameworks..." : ""} />
      </ComboboxChips>
      <ComboboxContent anchor={anchor}>
        <ComboboxEmpty>No results found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Clear button

Add showClear to ComboboxInput to display a clear button when a value is selected. The chevron is automatically hidden when the clear button is visible.


<Combobox items={frameworks}>
  <ComboboxInput placeholder="Select a framework..." className="w-56" showClear />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Groups

Use ComboboxGroup with ComboboxLabel to organize items into labelled sections. Pass an array of { label, items } objects to the items prop and use a render function that returns a ComboboxGroup per group.


const groupedFrameworks = [
  { label: "React", items: [{ value: "next.js", label: "Next.js" }, { value: "remix", label: "Remix" }] },
  { label: "Vue", items: [{ value: "nuxt.js", label: "Nuxt.js" }] },
  { label: "Other", items: [{ value: "sveltekit", label: "SvelteKit" }, { value: "astro", label: "Astro" }] },
]
 
<Combobox items={groupedFrameworks}>
  <ComboboxInput placeholder="Select a framework..." className="w-56" />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(group) => (
        <ComboboxGroup key={group.label}>
          <ComboboxLabel>{group.label}</ComboboxLabel>
          {group.items.map((item) => (
            <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
          ))}
        </ComboboxGroup>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Custom items

Compose ComboboxItem with icons, badges, or multi-line content to build richer option lists.


<ComboboxItem value="next.js" className="pr-8">
  <GitBranchIcon />
  <div className="flex flex-col">
    <span className="font-medium">Next.js</span>
    <span className="text-default-11 text-xs">React framework</span>
  </div>
</ComboboxItem>

Invalid and Disabled


{/* Invalid */}
<Field data-invalid="true">
  <FieldLabel>Framework</FieldLabel>
  <Combobox items={frameworks}>
    <ComboboxInput placeholder="Select a framework..." aria-invalid="true" />
    <ComboboxContent>
      <ComboboxEmpty>No results found.</ComboboxEmpty>
      <ComboboxList>
        {(item) => (
          <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
        )}
      </ComboboxList>
    </ComboboxContent>
  </Combobox>
  <FieldError>Please select a framework.</FieldError>
</Field>
 
{/* Disabled */}
<Combobox disabled items={frameworks}>
  <ComboboxInput placeholder="Select a framework..." disabled />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Auto-highlight

With autoHighlight, the first matching item is highlighted automatically as you type, so pressing Enter selects it immediately.


<Combobox autoHighlight items={frameworks}>
  <ComboboxInput placeholder="Type to search..." className="w-56" />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Pop-up

In the pop-up pattern, a styled trigger button shows the selected value and clicking it opens a popup that contains both the search input and the list. Useful when you want a select-like appearance with search capability.


<Combobox items={frameworks}>
  <ComboboxTrigger className="flex h-8 w-56 items-center justify-between gap-2 rounded-lg border bg-default-1 px-2.5 text-sm font-normal">
    <ComboboxValue placeholder="Select a framework..." />
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput showTrigger={false} placeholder="Search..." autoFocus />
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Input group

Pass an InputGroupAddon as a child of ComboboxInput to add a leading icon or prefix element.


import { InputGroupAddon } from "@/components/ui/input-group"
import { SearchIcon } from "lucide-react"
 
<Combobox items={frameworks}>
  <ComboboxInput placeholder="Search frameworks..." className="w-64">
    <InputGroupAddon align="inline-start">
      <SearchIcon />
    </InputGroupAddon>
  </ComboboxInput>
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Installation

Via CLI

terminal


npx shadcn@latest add https://solar-ui.com/r/combobox.json

Manual

1. Install the following dependency:

terminal


npm install @base-ui/react

2. Copy and paste the following code into your project:

components/ui/combobox.tsx


"use client"
 
import { Combobox as ComboboxPrimitive } from "@base-ui/react"
import * as React from "react"
 
import { Button } from "@/components/ui/button"
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
} from "@/components/ui/input-group"
import { cn } from "@/lib/utils"
import { CheckIcon, ChevronDownIcon, XIcon } from "lucide-react"
 
// ... see full source at components/ui/combobox.tsx

API

Combobox

Prop	Type	Default	Description
`items`	`object[]`	—	Array of items (or grouped items) used for filtering and the empty state. Each item must have a `value` field. For groups, use `{ label, items }[]`.
`value`	`string \| string[]`	—	Controlled selected value. Use `string[]` with `multiple`.
`defaultValue`	`string \| string[]`	—	Initial selected value (uncontrolled).
`onValueChange`	`(value: string \| string[]) => void`	—	Callback when the selection changes.
`multiple`	`boolean`	`false`	Allows selecting multiple items.
`disabled`	`boolean`	`false`	Disables the entire combobox.
`autoHighlight`	`boolean`	`false`	Automatically highlights the first matching item while typing.
`modal`	`boolean`	`false`	When `true`, interaction outside the popup is blocked.

ComboboxInput

Prop	Type	Default	Description
`placeholder`	`string`	—	Placeholder text shown when no value is entered.
`showTrigger`	`boolean`	`true`	Shows the chevron trigger button inside the input.
`showClear`	`boolean`	`false`	Shows a clear button when a value is selected. The trigger is hidden automatically while the clear button is visible.
`disabled`	`boolean`	`false`	Disables the input and its buttons.
`className`	`string`	—	Additional CSS classes applied to the wrapping `InputGroup`.

ComboboxContent

Prop	Type	Default	Description
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"bottom"`	Which side of the anchor the popup appears on.
`align`	`"start" \| "center" \| "end"`	`"start"`	Alignment of the popup relative to the anchor.
`sideOffset`	`number`	`6`	Distance in pixels between the popup and the anchor.
`anchor`	`React.RefObject`	—	Custom anchor element ref. Use with `useComboboxAnchor()` for the chips pattern.

ComboboxList

ComboboxList accepts either static ReactNode children or a render function (item, index) => ReactNode. Use the render function when you pass items to Combobox — this enables filtering and the empty state.

ComboboxItem

Prop	Type	Default	Description
`value`	`string`	—	The value submitted on selection. Also used for filtering.
`disabled`	`boolean`	`false`	Prevents the item from being selected.
`className`	`string`	—	Additional CSS classes.

ComboboxChip

Chips are positional — each ComboboxChip rendered corresponds to the selected value at the same index. Render them dynamically from your controlled state array.

Prop	Type	Default	Description
`showRemove`	`boolean`	`true`	Shows the remove button inside the chip.

ComboboxTrigger

A standalone trigger button that opens the popup. Use it with ComboboxValue to build a select-like appearance with search inside the popup.

useComboboxAnchor


const anchor = useComboboxAnchor()
// attach to the chips container
<ComboboxChips ref={anchor}>...</ComboboxChips>
// pass to the popup
<ComboboxContent anchor={anchor}>...</ComboboxContent>

Returns a ref that can be attached to any element to use it as the popup anchor instead of the default trigger.