---
title: "Integrate the Combobox UI component"
description: "Integrate a searchable dropdown component that combines an input field with a filterable list of options. Learn more in the docs."
canonical_url: "https://tiptap.dev/docs/ui-components/primitives/combobox"
---

# Integrate the Combobox UI component

Integrate a searchable dropdown component that combines an input field with a filterable list of options. Learn more in the docs.

A searchable dropdown component that combines an input field with a filterable list of options, built on top of Ariakit for accessibility and powered by advanced interaction patterns.

> **Interactive demo:** [combobox](https://template.tiptap.dev/preview/tiptap-ui-primitive/combobox)

## Install

You can add the primitive via Tiptap CLI

```bash
npx @tiptap/cli@latest add combobox
```

## Usage

```tsx
import React from 'react'
import {
  ComboboxProvider,
  Combobox,
  ComboboxPopover,
  ComboboxList,
  ComboboxItem,
} from '@/components/tiptap-ui-primitive/combobox'

const ALL_OPTIONS = ['Apple', 'Banana', 'Cherry', 'Date']

export default function MyComponent() {
  const [value, setValue] = React.useState('')

  const matches = ALL_OPTIONS.filter((opt) =>
    opt.toLowerCase().startsWith(value.toLowerCase())
  )

  return (
    <ComboboxProvider value={value} setValue={setValue}>
      <Combobox placeholder="Search options..." />
      <ComboboxPopover>
        <ComboboxList>
          {matches.map((opt) => (
            <ComboboxItem key={opt} value={opt}>
              {opt}
            </ComboboxItem>
          ))}
        </ComboboxList>
      </ComboboxPopover>
    </ComboboxProvider>
  )
}
```

## Props

### ComboboxProvider

Built on top of Ariakit's ComboboxProvider with optimized defaults.

| Name                | Type                      | Default | Description                                     |
| ------------------- | ------------------------- | ------- | ----------------------------------------------- |
| includesBaseElement | `boolean`                 | false   | Whether to include base element in tab sequence |
| resetValueOnHide    | `boolean`                 | true    | Whether to reset value when popover is hidden   |
| value               | `string`                  | -       | Current selected value                          |
| setValue            | `(value: string) => void` | -       | Function to update selected value               |

### Combobox

The input field component for typing and filtering.

| Name       | Type      | Default | Description                       |
| ---------- | --------- | ------- | --------------------------------- |
| autoSelect | `boolean` | true    | Automatically select first option |

### ComboboxItem

Individual selectable option within the combobox list.

| Name  | Type     | Default | Description                         |
| ----- | -------- | ------- | ----------------------------------- |
| value | `string` | -       | Value to select when item is chosen |

## Styling

The Combobox component uses CSS custom properties for theming:

```scss
.tiptap-combobox-list {
  --tt-combobox-bg-color: var(--white);
  --tt-combobox-border-color: var(--tt-gray-light-a-100);
  --tt-combobox-text-color: var(--tt-gray-light-a-600);

  .dark & {
    --tt-combobox-border-color: var(--tt-gray-dark-a-50);
    --tt-combobox-bg-color: var(--tt-gray-dark-50);
    --tt-combobox-text-color: var(--tt-gray-dark-a-600);
  }
}
```