pnpm dlx shadcn@latest add "https://godui.design/r/combobox.json"
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxItem,
ComboboxList,
} from "@/components/ui/combobox";
<Combobox items={frameworks}>
<ComboboxInput placeholder="Select a framework" />
<ComboboxContent>
<ComboboxEmpty>No items found.</ComboboxEmpty>
<ComboboxList>
{(item) => (
<ComboboxItem key={item} value={item}>
{item}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxContent>
</Combobox>
Built on Base UI Combobox Root; accepts all its props. Renders no element of its own.
| Prop | Type | Default | Description |
|---|
items | readonly any[] | readonly Group<any>[] | ComboboxItemCollection | none | Items to filter and render. ComboboxList and ComboboxCollection take a render function that receives each one. |
value | Value | Value[] | null | none | Selected value (an array when multiple). Use when controlled. |
defaultValue | Value | Value[] | null | none | Initial selected value when uncontrolled. |
onValueChange | (value, eventDetails) => void | none | Called when the selection changes. |
multiple | boolean | false | Allow selecting several items. Pair with ComboboxChips. |
inputValue | string | number | readonly string[] | none | Input text. Use when controlled. |
defaultInputValue | string | number | readonly string[] | none | Initial input text when uncontrolled. |
onInputValueChange | (inputValue: string, eventDetails) => void | none | Called when the input text changes. |
open | boolean | none | Whether the popup is open. Use when controlled. |
defaultOpen | boolean | false | Whether the popup starts open. |
onOpenChange | (open: boolean, eventDetails) => void | none | Called when the popup opens or closes. |
filter | ((item, query: string, itemToString?) => boolean) | null | none | Custom match function. null turns filtering off. |
itemToStringLabel | (itemValue: Value) => string | none | Label shown in the input for object values. |
autoHighlight | boolean | false | Highlight the first match while filtering. |
limit | number | -1 | Maximum number of items to show. -1 means no limit. |
disabled | boolean | false | Ignore user interaction. |
readOnly | boolean | false | Prevent choosing a different option. |
required | boolean | false | Require a value before the form submits. |
name | string | none | Field name for form submission. |
The text input, rendered inside an InputGroup with an optional trigger and clear button. Built on Base UI Combobox Input; accepts all its props. Extra children render inside the input group.
| Prop | Type | Default | Description |
|---|
showTrigger | boolean | true | Show the chevron button that toggles the popup. |
showClear | boolean | false | Show a button that clears the value. Hides the trigger when present. |
disabled | boolean | false | Disable the input, trigger and clear button. |
The animated popup, portaled and positioned against the input. Built on Base UI Combobox Popup; accepts all its props, plus these Positioner props.
| Prop | Type | Default | Description |
|---|
side | "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end" | "bottom" | Side of the anchor to open on. |
sideOffset | number | 6 | Distance from the anchor in pixels. |
align | "start" | "center" | "end" | "start" | Alignment against the anchor. |
alignOffset | number | 0 | Offset from the alignment edge in pixels. |
anchor | Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null | none | Element to position against. Pass the useComboboxAnchor() ref from ComboboxChips in multiple mode. |
The scrollable list. Built on Base UI Combobox List; accepts all its props. Children can be a render function (item, index) => ReactNode called for each filtered item.
An option with a check that pops in when it's selected. Built on Base UI Combobox Item; accepts all its props.
| Prop | Type | Default | Description |
|---|
value | any | null | The value this item selects. |
disabled | boolean | false | Make the item unselectable. |
Group items under a label. Built on Base UI Group, GroupLabel and Collection; each accepts all its props. ComboboxCollection renders a group's items with a render function.
ComboboxEmpty shows its content when no item matches. ComboboxSeparator draws a line between groups. Built on Base UI Empty and Separator; each accepts all its props.
The container for chips in multiple mode. Chips after a removed one slide into place. Built on Base UI Combobox Chips; accepts all its props.
A selected value shown as a chip. It pops in when added after the container mounted. Built on Base UI Combobox Chip; accepts all its props.
| Prop | Type | Default | Description |
|---|
showRemove | boolean | true | Show the × button that removes the chip. |
The text input placed inside ComboboxChips. Built on Base UI Combobox Input; accepts all its props.
ComboboxTrigger is a button that toggles the popup and appends a chevron. ComboboxValue renders the selected value. Built on Base UI Trigger and Value; each accepts all its props.
Returns a RefObject<HTMLDivElement | null>. Attach it to ComboboxChips and pass it to ComboboxContent's anchor so the popup lines up with the chips.
Props match shadcn/ui Combobox.