Combobox

Installation

npm install @base-ui/react

pnpm add @base-ui/react

yarn add @base-ui/react

bun add @base-ui/react

Or use the CLI:

npx shadcn@latest add combobox

Usage

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

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function ExampleCombobox() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Component API

The root component built on @base-ui/react Combobox primitive. Props:

items - Array of items to display
value - Controlled value
onValueChange - Callback when value changes
multiple - Enable multi-select mode
itemToStringValue - Convert object items to string
autoHighlight - Auto-highlight first item on filter
disabled - Disable the combobox

ComboboxInput

The input field for searching and selecting items. Props:

showTrigger - Show dropdown trigger button (default: true)
showClear - Show clear button (default: false)
disabled - Disable the input
placeholder - Placeholder text

ComboboxContent

The dropdown content container. Props:

side - Placement side (default: "bottom")
sideOffset - Offset from anchor (default: 6)
align - Alignment (default: "start")
alignOffset - Alignment offset (default: 0)
anchor - Custom anchor element

ComboboxItem

An individual selectable item. Props:

value - Item value
disabled - Disable the item

Examples

Custom Items

Use itemToStringValue when your items are objects:

type Framework = {
  label: string
  value: string
}

const frameworks: Framework[] = [
  { label: "Next.js", value: "next" },
  { label: "SvelteKit", value: "sveltekit" },
  { label: "Nuxt", value: "nuxt" },
]

export function CustomItemsExample() {
  return (
    <Combobox
      items={frameworks}
      itemToStringValue={(framework) => framework.label}
    >
      <ComboboxInput placeholder="Select a framework" />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(framework) => (
            <ComboboxItem key={framework.value} value={framework}>
              {framework.label}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Multiple Selection

Use multiple with chips for multi-select behavior:

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

const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]

export function MultipleExample() {
  const [value, setValue] = React.useState<string[]>([])

  return (
    <Combobox
      items={frameworks}
      multiple
      value={value}
      onValueChange={setValue}
    >
      <ComboboxChips>
        <ComboboxValue>
          {value.map((item) => (
            <ComboboxChip key={item}>{item}</ComboboxChip>
          ))}
        </ComboboxValue>
        <ComboboxChipsInput placeholder="Add framework" />
      </ComboboxChips>
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => (
            <ComboboxItem key={item} value={item}>
              {item}
            </ComboboxItem>
          )}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

With Groups

Organize items into labeled groups:

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

export function GroupsExample() {
  return (
    <Combobox>
      <ComboboxInput placeholder="Search..." />
      <ComboboxContent>
        <ComboboxEmpty>No items found.</ComboboxEmpty>
        <ComboboxList>
          <ComboboxGroup>
            <ComboboxLabel>Frameworks</ComboboxLabel>
            <ComboboxItem value="next">Next.js</ComboboxItem>
            <ComboboxItem value="svelte">SvelteKit</ComboboxItem>
          </ComboboxGroup>
          <ComboboxSeparator />
          <ComboboxGroup>
            <ComboboxLabel>Libraries</ComboboxLabel>
            <ComboboxItem value="react">React</ComboboxItem>
            <ComboboxItem value="vue">Vue</ComboboxItem>
          </ComboboxGroup>
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

Clear Button

Use the showClear prop to show a clear button:

<Combobox items={frameworks}>
  <ComboboxInput showClear placeholder="Select a framework" />
  <ComboboxContent>
    {/* ... */}
  </ComboboxContent>
</Combobox>

Invalid State

Use the aria-invalid prop to mark the combobox as invalid:

<Combobox items={frameworks}>
  <ComboboxInput aria-invalid placeholder="Select a framework" />
  <ComboboxContent>
    {/* ... */}
  </ComboboxContent>
</Combobox>

Disabled

Use the disabled prop to disable the combobox:

<Combobox items={frameworks} disabled>
  <ComboboxInput placeholder="Select a framework" />
  <ComboboxContent>
    {/* ... */}
  </ComboboxContent>
</Combobox>

Accessibility

Built on @base-ui/react for full accessibility support
Keyboard navigation with arrow keys
Type-ahead search functionality
Screen reader announcements for state changes
Focus management

API Reference

See the Base UI Combobox documentation for complete API details.

​Installation

​Usage

​Component API

​Combobox

​ComboboxInput

​ComboboxContent

​ComboboxItem

​Examples

​Custom Items

​Multiple Selection

​With Groups

​Clear Button

​Invalid State

​Disabled

​Accessibility

​API Reference