# Combobox (/docs/components/combobox)



<ComponentPreview name="combobox-demo" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

## Overview [#overview]

Use a combobox when users choose one or more values from a list and search or filtering helps them find the right option.

Combobox is useful for large lists, people pickers, labels, projects, countries, commands, and multi-select workflows.

## Anatomy [#anatomy]

A combobox has a trigger or input, popup, list, items, and selection state. Single-selection comboboxes store one value. Multiple-selection comboboxes store a list of values.

## Behavior [#behavior]

Use single selection when one value is allowed. Use multiple selection for tags, filters, permissions, or categories. Use clear buttons when users often reset the value.

## Accessibility [#accessibility]

Give the combobox a label and keep keyboard navigation intact. Users should be able to open the popup, move through options, select items, clear values, and close the popup without a mouse.

## Installation [#installation]

<CodeTabs>
  <TabsList>
    <TabsTab value="cli">
      CLI
    </TabsTab>

    <TabsTab value="manual">
      Manual
    </TabsTab>
  </TabsList>

  <TabsPanel value="cli">
    ```bash
    npx love-ui@latest add combobox
    ```
  </TabsPanel>

  <TabsPanel value="manual">
    <Steps>
      <Step>
        Install the following dependencies:
      </Step>

      ```bash
      npm install @base-ui-components/react
      ```

      <Step>
        Copy and paste the following code into your project.
      </Step>

      <ComponentSource name="combobox" title="components/ui/combobox.tsx" />

      <Step>
        Update the import paths to match your project setup.
      </Step>
    </Steps>
  </TabsPanel>
</CodeTabs>

## Usage [#usage]

### Single Selection [#single-selection]

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

```tsx
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items}>
  <ComboboxInput placeholder="Select an item..." />
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

### Multiple Selection [#multiple-selection]

```tsx
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
} from "@/components/ui/combobox"
```

```tsx
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(value: { value: string; label: string }[]) => (
        <>
          {value?.map((item) => (
            <ComboboxChip key={item.value} aria-label={item.value}>
              {item.label}
            </ComboboxChip>
          ))}
          <ComboboxInput
            placeholder={value.length > 0 ? undefined : "Select a Select an item..."}
            aria-label="Select an item"
          />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

## API Reference [#api-reference]

The `ComboboxInput` component extends the original Base UI component with a few extra props:

| Prop          | Type                        | Default     | Description                                                                                      |
| ------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `size`        | `"sm" \| "default" \| "lg"` | `"default"` | The size variant of the input field.                                                             |
| `showTrigger` | `boolean`                   | `true`      | Whether to display a trigger button (chevron icon) on the right side of the input.               |
| `showClear`   | `boolean`                   | `false`     | Whether to display a clear button (X icon) on the right side of the input when there is a value. |

## Examples [#examples]

The examples show disabled, sized, labeled, grouped, single-selection, multiple-selection, input-in-popup, and form-connected comboboxes.

### Disabled [#disabled]

<ComponentPreview name="combobox-disabled" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### Small Size [#small-size]

<ComponentPreview name="combobox-sm" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### Large Size [#large-size]

<ComponentPreview name="combobox-lg" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### With Label [#with-label]

<ComponentPreview name="combobox-with-label" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### Auto Highlight [#auto-highlight]

Automatically highlight the first matching option.

<ComponentPreview name="combobox-autohighlight" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### With Clear Button [#with-clear-button]

<ComponentPreview name="combobox-with-clear" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### With Groups [#with-groups]

<ComponentPreview name="combobox-grouped" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### With Multiple Selection [#with-multiple-selection]

<ComponentPreview name="combobox-multiple" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### With Input Inside Popup [#with-input-inside-popup]

<ComponentPreview name="combobox-with-inner-input" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### Form Integration [#form-integration]

<ComponentPreview name="combobox-form" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />

### Form Integration - Multiple [#form-integration---multiple]

<ComponentPreview name="combobox-multiple-form" className="[&_.preview>*]:w-full [&_.preview>*]:max-w-64" />