Installation
Installation with shadcn/ui
CLI
Manual
Install the following dependencies:
Copy and paste the following code into your project.
Layout
Import the parts, and compose them together.
Examples
With Groups
With Multiple Selection
With Custom Filter
With Debounce
With Virtualization
With Tags Input
API Reference
Root
The container for all combobox parts.
Prop | Type | Default |
---|---|---|
defaultValue | Value<Multiple> | - |
value | Value<Multiple> | - |
onValueChange | (value: Value<Multiple>) => void | - |
asChild | boolean | - |
open | boolean | - |
defaultOpen | boolean | false |
onOpenChange | (open: boolean) => void | - |
inputValue | string | - |
onInputValueChange | (value: string) => void | - |
onFilter | (options: string[], inputValue: string) => string[] | - |
autoHighlight | boolean | false |
disabled | boolean | - |
exactMatch | boolean | false |
manualFiltering | boolean | true |
loop | boolean | false |
modal | boolean | false |
multiple | Multiple | false |
openOnFocus | boolean | false |
preserveInputOnBlur | boolean | false |
readOnly | boolean | false |
required | boolean | false |
name | string | - |
Data Attribute | Value |
---|---|
[data-state] | "open" | "closed" |
[data-disabled] | Present when disabled. |
Label
An accessible label that describes the combobox. Associates with the input element for screen readers.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Anchor
A wrapper element that positions the combobox popover relative to the input and trigger. Provides the reference point for popover positioning.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
preventInputFocus | boolean | false |
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. |
Trigger
A button that toggles the combobox popover. Handles focus management and keyboard interactions for opening/closing the popover.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Data Attribute | Value |
---|---|
[data-state] | "open" | "closed" |
[data-disabled] | Present when disabled |
Input
The text input field that users can type into to filter options.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
BadgeList
A container for displaying selected items as badges in a multi-select combobox.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
forceMount | boolean | false |
orientation | "horizontal" | "vertical" | "horizontal" |
Data Attribute | Value |
---|---|
[data-orientation] | "horizontal" | "vertical" |
BadgeItem
An individual badge representing a selected item in a multi-select combobox.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
value | string | - |
disabled | boolean | false |
Data Attribute | Value |
---|---|
[data-disabled] | Present when the badge is disabled. |
[data-highlighted] | Present when the badge is highlighted. |
[data-orientation] | "horizontal" | "vertical" |
BadgeItemDelete
A button to remove a selected item from the multi-select combobox.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Data Attribute | Value |
---|---|
[data-disabled] | Present when the parent badge is disabled. |
[data-highlighted] | Present when the parent badge is highlighted. |
Cancel
A button that clears the input value and resets the filter.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
forceMount | boolean | false |
Portal
A portal for rendering the combobox content outside of its DOM hierarchy.
Prop | Type | Default |
---|---|---|
container | HTMLElement | DocumentFragment | document.body |
Content
The popover container for combobox items. Positions the combobox popover relative to the anchor.
Prop | Type | Default |
---|---|---|
side | Side | "bottom" |
sideOffset | number | 4 |
align | Align | "start" |
alignOffset | number | 0 |
collisionBoundary | Boundary | - |
collisionPadding | number | Partial<Record<Side, number>> | 0 |
arrowPadding | number | 0 |
sticky | "partial" | "always" | "partial" |
strategy | Strategy | "absolute" |
avoidCollisions | boolean | true |
fitViewport | boolean | false |
forceMount | boolean | false |
hideWhenDetached | boolean | false |
trackAnchor | boolean | true |
asChild | boolean | - |
onEscapeKeyDown | (event: KeyboardEvent) => void | - |
onPointerDownOutside | (event: PointerDownOutsideEvent) => void | - |
Data Attribute | Value |
---|---|
[data-state] | "open" | "closed" |
[data-side] | "top" | "right" | "bottom" | "left" |
[data-align] | "start" | "center" | "end" |
CSS Variable | Description | Default |
---|---|---|
--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. | — |
Arrow
A visual arrow element that points to the anchor.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Progress
A loading indicator for asynchronous filtering operations.
Prop | Type | Default |
---|---|---|
label | string | - |
asChild | boolean | - |
value | number | null |
max | number | 100 |
Empty
A placeholder component displayed when no options match the current filter.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
keepVisible | boolean | false |
Group
A container for logically grouping related options.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
forceMount | boolean | false |
GroupLabel
A label that describes a group of options.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
Item
An interactive item in the combobox list.
Prop | Type | Default |
---|---|---|
label | string | - |
onSelect | (value: string) => void | - |
asChild | boolean | - |
value | string | - |
disabled | boolean | - |
Data Attribute | Value |
---|---|
[data-highlighted] | Present when the item is highlighted. |
[data-disabled] | Present when the item is disabled. |
[data-state] | "checked" | "unchecked" |
ItemText
The textual content of an item.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
ItemIndicator
A visual indicator for selected options.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
forceMount | boolean | false |
Separator
A visual divider for separating options or groups.
Prop | Type | Default |
---|---|---|
asChild | boolean | - |
keepVisible | boolean | false |
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. |