Combobox

Installation

pnpm dlx shadcn@latest add https://prototyper-ui.com/r/combobox.json

npx shadcn@latest add https://prototyper-ui.com/r/combobox.json

yarn dlx shadcn@latest add https://prototyper-ui.com/r/combobox.json

bunx --bun shadcn@latest add https://prototyper-ui.com/r/combobox.json

This will add the following files to your project:

components/ui/combobox.tsx

Usage

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

<Combobox items={items}>
  <ComboboxInput placeholder="Search..." />
  <ComboboxContent>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Anatomy

<Combobox>
  <ComboboxInput />
  <ComboboxContent>
    <ComboboxEmpty />
    <ComboboxGroup>
      <ComboboxGroupLabel />
      <ComboboxList>
        <ComboboxItem />
      </ComboboxList>
    </ComboboxGroup>
  </ComboboxContent>
</Combobox>

Or with chips for multi-select:

<Combobox>
  <ComboboxChips>
    <ComboboxChip>
      <ComboboxChipRemove />
    </ComboboxChip>
    <ComboboxChipsInput />
  </ComboboxChips>
  <ComboboxContent>
    <ComboboxList>
      <ComboboxItem />
    </ComboboxList>
  </ComboboxContent>
</Combobox>

Sub-component	`data-slot`	Purpose	Required
`Combobox`	-	Root provider, manages state and filtering	Yes
`ComboboxInput`	`input-group-control`	Text input with optional trigger and clear buttons	Yes*
`ComboboxChipsInput`	`combobox-chips-input`	Text input for use inside `ComboboxChips`	Yes*
`ComboboxTrigger`	`combobox-trigger`	Button that toggles the popup open/closed	No
`ComboboxClear`	`combobox-clear`	Button that clears the current selection	No
`ComboboxValue`	`combobox-value`	Displays the selected value	No
`ComboboxContent`	`combobox-content`	Positioned popup containing the list	Yes
`ComboboxList`	`combobox-list`	Scrollable list of items	Yes
`ComboboxItem`	`combobox-item`	Individual selectable option	Yes
`ComboboxEmpty`	`combobox-empty`	Shown when no items match the filter	No
`ComboboxGroup`	`combobox-group`	Groups related items together	No
`ComboboxGroupLabel`	`combobox-group-label`	Label for a group of items	No
`ComboboxSeparator`	`combobox-separator`	Visual separator between groups	No
`ComboboxIcon`	`combobox-icon`	Icon element inside the combobox	No
`ComboboxChips`	`combobox-chips`	Container for selected chips in multi-select mode	No
`ComboboxChip`	`combobox-chip`	Individual chip representing a selected value	No
`ComboboxChipRemove`	`combobox-chip-remove`	Button to remove a chip	No
`ComboboxStatus`	`combobox-status`	Screen-reader-only status message	No
`ComboboxArrow`	`combobox-arrow`	Arrow pointing from popup to trigger	No
`ComboboxBackdrop`	`combobox-backdrop`	Full-screen backdrop behind the popup	No

* Use either ComboboxInput or ComboboxChipsInput, not both.

Examples

Content

Description

Framework

Choose the framework you use for your projects.

Disabled

Disabled Items

Filtering

Multiple

Sections

Text Slots

Validation

Styling

Data Slots

Use data-slot attributes to target specific parts of the combobox:

Slot name	Element
`input-group-control`	The text input element
`combobox-trigger`	Dropdown trigger button
`combobox-clear`	Clear selection button
`combobox-content`	Positioned popup panel
`combobox-list`	Scrollable list container
`combobox-item`	Individual option
`combobox-empty`	Empty state message
`combobox-group`	Group container
`combobox-group-label`	Group label
`combobox-separator`	Separator line between groups
`combobox-chips`	Chips container for multi-select
`combobox-chip`	Individual chip
`combobox-chip-remove`	Chip remove button
`combobox-chips-input`	Input within chips container
`combobox-value`	Selected value display
`combobox-icon`	Icon element
`combobox-status`	Screen-reader status (visually hidden)
`combobox-arrow`	Popup arrow
`combobox-backdrop`	Full-screen backdrop

Customization Examples

/* Widen the popup */
[data-slot="combobox-content"] {
  @apply min-w-[20rem];
}

/* Custom highlighted item style */
[data-slot="combobox-item"][data-highlighted] {
  @apply bg-primary text-primary-foreground;
}

{/* Override popup alignment */}
<ComboboxContent align="center" sideOffset={8}>
  {/* ... */}
</ComboboxContent>

API Reference

Root component that manages filtering, selection, and open/close state.

All Base UI Combobox.Root props are forwarded via ...props.

ComboboxInput

Text input with optional trigger and clear buttons, wrapped in an InputGroup.

Prop

Type

All Base UI Combobox.Input props are forwarded via ...props.

ComboboxChipsInput

Minimal text input for use within the ComboboxChips container.

Prop

Type

All Base UI Combobox.Input props are forwarded via ...props.

ComboboxTrigger

Button that toggles the popup open or closed. Renders a chevron-down icon by default.

Prop

Type

All Base UI Combobox.Trigger props are forwarded via ...props.

ComboboxClear

Button that clears the current selection. Renders an X icon by default.

Prop

Type

All Base UI Combobox.Clear props are forwarded via ...props.

ComboboxValue

Displays the selected value text.

All Base UI Combobox.Value props are forwarded via ...props.

ComboboxContent

Positioned popup that contains the list. Wraps Combobox.Portal, Combobox.Positioner, and Combobox.Popup.

Prop

Type

All Base UI Combobox.Popup props are forwarded via ...props.

ComboboxList

Scrollable list container for combobox items.

Prop

Type

All Base UI Combobox.List props are forwarded via ...props.

ComboboxItem

Individual selectable option. Includes a check icon indicator when selected.

Prop

Type

All Base UI Combobox.Item props are forwarded via ...props.

ComboboxEmpty

Message shown when no items match the current filter.

Prop

Type

All Base UI Combobox.Empty props are forwarded via ...props.

ComboboxGroup

Groups related combobox items together.

Prop

Type

All Base UI Combobox.Group props are forwarded via ...props.

ComboboxGroupLabel

Label for a group of items.

Prop

Type

All Base UI Combobox.GroupLabel props are forwarded via ...props.

ComboboxSeparator

Visual separator between groups.

Prop

Type

All Base UI Combobox.Separator props are forwarded via ...props.

ComboboxIcon

Icon element within the combobox.

Prop

Type

All Base UI Combobox.Icon props are forwarded via ...props.

ComboboxChips

Container for selected value chips in multi-select mode.

Prop

Type

All Base UI Combobox.Chips props are forwarded via ...props.

ComboboxChip

Individual chip representing a selected value.

Prop

Type

All Base UI Combobox.Chip props are forwarded via ...props.

ComboboxChipRemove

Button to remove a chip. Renders an X icon by default.

Prop

Type

All Base UI Combobox.ChipRemove props are forwarded via ...props.

ComboboxStatus

Screen-reader-only status message that announces changes.

Prop

Type

All Base UI Combobox.Status props are forwarded via ...props.

ComboboxArrow

Arrow element pointing from the popup to the trigger.

Prop

Type

All Base UI Combobox.Arrow props are forwarded via ...props.

ComboboxBackdrop

Full-screen backdrop rendered behind the popup.

Prop

Type

All Base UI Combobox.Backdrop props are forwarded via ...props.

ComboboxCollection

Re-export of ComboboxPrimitive.Collection for defining static item collections.

useComboboxFilter

Re-export of ComboboxPrimitive.useFilter hook for custom filtering logic.

useComboboxAnchor

Utility hook that returns a ref for anchoring the combobox popup to a custom element.

import { useComboboxAnchor } from "@/components/ui/combobox"

const anchorRef = useComboboxAnchor()

Accessibility

Keyboard Interactions

Key	Action
`ArrowDown`	Opens the popup (if closed) or moves to the next item
`ArrowUp`	Opens the popup (if closed) or moves to the previous item
`Enter`	Selects the highlighted item and closes the popup
`Escape`	Closes the popup
`Home`	Moves to the first item in the list
`End`	Moves to the last item in the list
`Tab`	Closes the popup and moves focus to the next element
`Backspace`	Removes the last chip (in multi-select chips mode)

ARIA Attributes

The input has role="combobox" with aria-expanded indicating popup state.
aria-activedescendant tracks the currently highlighted item.
aria-autocomplete indicates the filtering behavior.
ComboboxContent has role="listbox" for the list of options.
ComboboxItem has role="option" with aria-selected for selected state and aria-disabled for disabled items.
ComboboxGroup uses role="group" with aria-labelledby linked to the group label.
ComboboxStatus provides a live region for screen reader announcements.
ComboboxClear has aria-label="Clear selection" for screen reader users.

Combobox

On this page