Combobox

Combobox combines text input with a filterable list of options. It supports keyboard navigation, single or multiple values, grouped collections, clear actions, and an explicit empty state through Base UI.

Use it when users need to search a list that is too long for a small set of visible choices. For a handful of options, prefer a radio group or select so every choice is easier to scan.

Live previewInteractive / Local

Environment

Installation

Sourcebash

pnpm dlx shadcn@latest add http://ui.argv-tech.dev/r/combobox.json

Usage

Sourcetsx

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

const environments = ["Production", "Staging", "Preview"]

<Combobox items={environments}>
    <ComboboxInput aria-label="Environment" placeholder="Search environments" />
    <ComboboxContent>
        <ComboboxEmpty>No environments found.</ComboboxEmpty>
        <ComboboxList>
            {environments.map((environment) => (
                <ComboboxItem key={environment} value={environment}>
                    {environment}
                </ComboboxItem>
            ))}
        </ComboboxList>
    </ComboboxContent>
</Combobox>

Composition

Sourcetext

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxItem
        ├── ComboboxSeparator
        └── ComboboxItem

For multiple selection, replace ComboboxInput with a chips composition:

Sourcetext

Combobox
├── ComboboxChips
│   ├── ComboboxChip
│   └── ComboboxChipsInput
└── ComboboxContent
    └── ComboboxList
        └── ComboboxItem

Combobox exports styled wrappers around the Base UI root, value, input, trigger, clear, popup, list, item, group, label, collection, empty, separator, chips, and chip input primitives. It also exports useComboboxAnchor for popup positioning around a chips container.

ComboboxInput composes InputGroup and accepts showTrigger and showClear. Both default to true and false respectively. Set showClear when users should be able to remove the current value without editing the input manually.

Pass items to Combobox when Base UI should filter a collection. Use multiple with ComboboxChips, ComboboxChip, and ComboboxChipsInput when several values may be selected.

API Reference

Combobox

Combobox is the Base UI root. Its value type follows the supplied items collection and whether multiple is enabled.

Prop	Type	Default
`items`	collection	-
`defaultValue`	item or item array	-
`value`	item or item array	-
`onValueChange`	function	-
`multiple`	`boolean`	`false`
`disabled`	`boolean`	`false`

ComboboxInput

Prop	Type	Default
`showTrigger`	`boolean`	`true`
`showClear`	`boolean`	`false`
`disabled`	`boolean`	`false`
`className`	`string`	-

The remaining props are forwarded to the Base UI input primitive.

ComboboxContent

Prop	Type	Default
`side`	Positioner side	`"bottom"`
`sideOffset`	`number`	`6`
`align`	Positioner alignment	`"start"`
`alignOffset`	`number`	`0`
`anchor`	anchor element or ref	-
`className`	`string`	-

ComboboxChip

Prop	Type	Default
`showRemove`	`boolean`	`true`
`className`	`string`	-

ComboboxValue, ComboboxTrigger, ComboboxList, ComboboxItem, ComboboxGroup, ComboboxLabel, ComboboxCollection, ComboboxEmpty, ComboboxSeparator, ComboboxChips, and ComboboxChipsInput forward their corresponding Base UI primitive props.

Accessibility

Give the input a visible label connected through id and htmlFor, or provide aria-label. The built-in icon controls rendered by ComboboxInput are labeled “Open options” and “Clear selection.”

Keyboard interaction follows the Base UI combobox pattern: the arrow keys move through options, Enter selects the highlighted option, and Escape closes the popup. Keep option text concise and provide a meaningful ComboboxEmpty message when filtering returns no matches.