Dice UI

Trick

Installation

pnpm add @diceui/combobox

Installation with shadcn/ui

pnpm dlx shadcn@latest add @diceui/combobox

Layout

Import the parts, and compose them together.

import {
  Combobox,
  ComboboxLabel,
  ComboboxAnchor,
  ComboboxBadgeList,
  ComboboxBadgeItem,
  ComboboxBadgeItemDelete,
  ComboboxInput,
  ComboboxTrigger,
  ComboboxCancel,
  ComboboxPortal,
  ComboboxContent,
  ComboboxArrow,
  ComboboxLoading,
  ComboboxEmpty,
  ComboboxGroup,
  ComboboxGroupLabel,
  ComboboxItem,
  ComboboxItemText,
  ComboboxItemIndicator,
  ComboboxSeparator,
} from "@diceui/combobox";
 
return (
  <Combobox>
    <ComboboxLabel />
    <ComboboxAnchor>
      <ComboboxBadgeList>
        <ComboboxBadgeItem>
          <ComboboxBadgeItemDelete />
        </ComboboxBadgeItem>
      </ComboboxBadgeList>
      <ComboboxInput />
      <ComboboxTrigger />
      <ComboboxCancel />
    </ComboboxAnchor>
    <ComboboxPortal>
      <ComboboxContent>
        <ComboboxArrow />
        <ComboboxLoading />
        <ComboboxEmpty />
        <ComboboxGroup>
          <ComboboxGroupLabel />
          <ComboboxItem>
            <ComboboxItemText />
            <ComboboxItemIndicator />
          </ComboboxItem>
        </ComboboxGroup>
        <ComboboxSeparator />
      </ComboboxContent>
    </ComboboxPortal>
  </Combobox>
)

Examples

With Groups

Trick

With Multiple Selection

Tricks

With Custom Filter

Trick

With Debounce

Trick

With Virtualization

Trick

With Tags Input

API Reference

Combobox

The container for all combobox parts.

Prop

Type

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled

ComboboxLabel

An accessible label that describes the combobox. Associates with the input element for screen readers.

Prop

Type

ComboboxAnchor

A wrapper element that positions the combobox popover relative to the input and trigger. Provides the reference point for popover positioning.

Prop

Type

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-anchor]`	Present when the anchor is present
`[data-disabled]`	Present when disabled
`[data-focused]`	Present when the anchor is focused

ComboboxTrigger

A button that toggles the combobox popover. Handles focus management and keyboard interactions for opening/closing the popover.

Prop

Type

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-disabled]`	Present when disabled

ComboboxInput

The text input field that users can type into to filter options.

Prop

Type

ComboboxBadgeList

A container for displaying selected items as badges in a multi-select combobox.

Prop

Type

Data Attribute	Value
`[data-orientation]`	`"horizontal" \| "vertical"`

ComboboxBadgeItem

An individual badge representing a selected item in a multi-select combobox.

Prop

Type

Data Attribute	Value
`[data-disabled]`	Present when the badge is disabled
`[data-highlighted]`	Present when the badge is highlighted
`[data-orientation]`	`"horizontal" \| "vertical"`

ComboboxBadgeItemDelete

A button to remove a selected item from the multi-select combobox.

Prop

Type

Data Attribute	Value
`[data-disabled]`	Present when the parent badge is disabled
`[data-highlighted]`	Present when the parent badge is highlighted

ComboboxCancel

A button that clears the input value and resets the filter.

Prop

Type

Data Attribute	Value
`[data-disabled]`	Present when disabled

ComboboxPortal

A portal for rendering the combobox content outside of its DOM hierarchy.

Prop

Type

ComboboxContent

The popover container for combobox items. Positions the combobox popover relative to the anchor.

Prop

Type

Data Attribute	Value
`[data-state]`	`"open" \| "closed"`
`[data-side]`	`"top" \| "right" \| "bottom" \| "left"`
`[data-align]`	`"start" \| "center" \| "end"`

CSS Variable	Description
`--dice-transform-origin`	Transform origin for anchor positioning.
`--dice-anchor-width`	Width of the anchor element.
`--dice-anchor-height`	Height of the anchor element.
`--dice-available-width`	Available width in the viewport for the popover element.
`--dice-available-height`	Available height in the viewport for the popover element.

ComboboxArrow

A visual arrow element that points to the anchor.

Prop

Type

ComboboxLoading

A loading indicator for asynchronous filtering operations.

Prop

Type

ComboboxEmpty

A placeholder component displayed when no options match the current filter.

Prop

Type

ComboboxGroup

A container for logically grouping related options.

Prop

Type

ComboboxGroupLabel

A label that describes a group of options.

Prop

Type

ComboboxItem

An interactive item in the combobox list.

Prop

Type

Data Attribute	Value
`[data-highlighted]`	Present when the item is highlighted
`[data-disabled]`	Present when the item is disabled
`[data-state]`	`"checked" \| "unchecked"`

ComboboxItemText

The textual content of an item.

Prop

Type

ComboboxItemIndicator

A visual indicator for selected options.

Prop

Type

ComboboxSeparator

A visual divider for separating options or groups.

Prop

Type

Accessibility

Keyboard Interactions

Key	Description
`Enter`	When open, selects the highlighted option. When a badge is highlighted in multiple mode, removes the badge.
`ArrowUp`	When open, highlights the previous option.
`ArrowDown`	When open, highlights the next option.
`ArrowLeft`	In multiple mode: When cursor is at start of input, closes the menu and highlights the last badge. When a badge is highlighted, moves highlight to previous badge.
`ArrowRight`	In multiple mode: When a badge is highlighted, moves highlight to next badge. If on last badge, removes highlight and focuses input.
`BackspaceDelete`	In multiple mode: When input is empty, removes the last badge. When a badge is highlighted, removes the highlighted badge.
`Home`	When open, highlights the first option.
`End`	When open, highlights the last option.
`PageUp`	When open and modal is enabled, highlights the previous option.
`PageDown`	When open and modal is enabled, highlights the next option.
`Escape`	Closes the combobox popover, returns focus to the input, and resets or restores the input value.

Combobox

On this page