Combobox

Autocomplete input and command palette with a list of suggestions.

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>
  )
}

Installation

pnpm dlx cubix@latest add combobox --base aria

Usage

Import

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

Example

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>
  )
}

Composition

Simple

A single-line input and a flat list.

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem

With chips

Multi-select with multiple, chips, and a chips input.

Combobox
├── ComboboxChips
│   ├── ComboboxValue
│   │   └── ComboboxChip
│   └── ComboboxChipsInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem

With groups and collection

Nested items per group using ComboboxCollection inside each ComboboxGroup.

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxCollection
        │       ├── ComboboxItem
        │       └── ComboboxItem
        ├── ComboboxSeparator
        └── ComboboxGroup
            ├── ComboboxLabel
            └── ComboboxCollection
                ├── ComboboxItem
                └── ComboboxItem

Examples

Basic

A simple combobox with a list of frameworks.

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>
  )
}

Multiple

Use multiple with chips for multi-select behavior.

Next.js

<Combobox items={frameworks} multiple autoHighlight>
  <ComboboxChips>
    <ComboboxValue>
      {(values) => (
        <>
          {values.map((value) => (
            <ComboboxChip key={value}>{value}</ComboboxChip>
          ))}
          <ComboboxChipsInput />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxContent>
    <ComboboxEmpty>No items found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Clear Button

Use the showClear prop to show a clear button.

<ComboboxInput showClear />

Groups

Use ComboboxGroup and ComboboxSeparator to group items.

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxCollection
        │       ├── ComboboxItem
        │       └── ComboboxItem
        ├── ComboboxSeparator
        └── ComboboxGroup
            ├── ComboboxLabel
            └── ComboboxCollection
                ├── ComboboxItem
                └── ComboboxItem

Custom Items

Use itemToStringValue when your items are objects, and render custom item content.

type Framework = {
  label: string
  value: string
}

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

<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>

Invalid

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

<ComboboxInput aria-invalid="true" />

Disabled

Use the disabled prop to disable the combobox.

<ComboboxInput disabled />

Auto Highlight

Use the autoHighlight prop to automatically highlight the first item on filter.

<Combobox items={frameworks} autoHighlight>

Popup

Trigger the combobox from a button. Move ComboboxInput inside ComboboxContent.

<Combobox items={countries} defaultValue={countries[0]}>
  <ComboboxTrigger
    render={
      <Button variant="outline" className="w-64 justify-between font-normal" />
    }
  >
    <ComboboxValue />
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput showTrigger={false} placeholder="Search" />
    <ComboboxEmpty>No items found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item.code} value={item}>
          {item.label}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Input Group

Add an addon inside ComboboxInput with InputGroupAddon.

<ComboboxInput placeholder="Select a timezone">
  <InputGroupAddon>
    <GlobeIcon />
  </InputGroupAddon>
</ComboboxInput>

API Reference

Note: See the Base UI Combobox docs for the full primitive API.

Combobox

The root that holds items, value, and filter state.

Prop	Type	Default	Description
items	T[]	-	The collection used to render and filter the list.
value	T \| T[] \| null	-	Controlled selected value. Use an array when multiple is set.
defaultValue	T \| T[] \| null	-	Initial selected value when uncontrolled.
onValueChange	(value: T \| T[] \| null) => void	-	Called when the selected value changes.
multiple	boolean	false	Allow more than one selected item.
autoHighlight	boolean	false	Automatically highlight the first matching item while filtering.
itemToStringValue	(item: T) => string	-	Map an object item to the string used for filtering and display.
disabled	boolean	false	Disable the combobox.

ComboboxInput

Prop	Type	Default	Description
showTrigger	boolean	true	Show the dropdown trigger inside the input group.
showClear	boolean	false	Show a button that clears the selected value.
placeholder	string	-	Placeholder text for the input.
disabled	boolean	-	Disable the input.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

ComboboxContent

Prop	Type	Default	Description
side	"top" \| "bottom" \| "left" \| "right" \| "inline-start" \| "inline-end"	"bottom"	Preferred side of the popup.
align	"start" \| "center" \| "end"	"start"	Alignment of the popup relative to the anchor.
sideOffset	number	6	Distance in pixels from the anchor.
anchor	RefObject<HTMLElement>	-	Custom anchor, used with chips for multi-select.