Combobox

When to UseCopy Anchor Link

• to choose from a list long enough to search, such as the client of an invoice
• to choose several options from one list, like the clients on a report

When Not to UseCopy Anchor Link

• for a short list that needs no typing (use a Select)
• for free text, as a Combobox only accepts a value from its list (use an Input)
• to search for an action and run it (use Command)

See Select for a comparison of the Select, the Native Select, and the Combobox.

AnatomyCopy Anchor Link

A Combobox is a field and the list that it opens. If multiple is set, the field shows a chip for each value.

FieldCopy Anchor Link

ComboboxInput renders an Input Group that contains the input, the trigger, and the clear button. Its className is applied to the group.

ListCopy Anchor Link

ComboboxContent renders the portal and the popup, and ComboboxItem adds the check. ComboboxEmpty is shown in place of the list when no option matches. To divide a list, use ComboboxGroup, ComboboxLabel, and ComboboxSeparator as you would use their counterparts in a Select.

ChipsCopy Anchor Link

If multiple is set, use ComboboxChips in place of ComboboxInput. ComboboxValue provides the selected values, and you render a ComboboxChip for each one.

StatesCopy Anchor Link

To disable a Combobox, set disabled on ComboboxInput. To mark a Combobox as invalid, set invalid on its Field, or set aria-invalid on ComboboxInput or ComboboxChipsInput, not on Combobox.

BehaviorCopy Anchor Link

A Combobox isn’t modal: the page stays interactive while the list is open.

Position and SizeCopy Anchor Link

By default, the list opens below the field and is as wide as the field. It has a maximum height of 252px and scrolls when its options are taller.

Clear ButtonCopy Anchor Link

If showClear is set on ComboboxInput, a clear button replaces the trigger while a value is set. The clear button isn’t in the tab order, so Tab skips it. Keyboard users can clear the value by pressing Escape when the list is closed.

ContentCopy Anchor Link

The names of the trigger, the clear button, and a chip’s remove button are set in labels.combobox: “Open popup”, “Clear”, and “Remove” by default. To translate them, use the Summit Provider.

AccessibilityCopy Anchor Link

Base UI’s Combobox sets the roles and keeps focus in the input. aria-activedescendant on the input points to the highlighted option.

KeyboardCopy Anchor Link

RequirementsCopy Anchor Link

InstallationCopy Anchor Link

npx shadcn@latest add @summit/combobox

The CLI also adds @summit/button, @summit/input-group, and @summit/summit-provider.

UsageCopy Anchor Link

You provide the options. To have them filtered as users type, pass them to items on Combobox, and pass ComboboxList a function that renders one option. Base UI filters items and calls the function for each match. If you write the options as children of ComboboxList, they aren’t filtered.

If an option has the shape { label, value }, its label is shown in the input.

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

const clients = [
    { label: 'Atelier Brume', value: 'brume' },
    { label: 'Fable Bakery', value: 'bakery' },
];

<Combobox items={clients}>
    <ComboboxInput aria-label="Client" placeholder="Choose a client" className="w-64" />
    <ComboboxContent>
        <ComboboxEmpty>No clients found.</ComboboxEmpty>
        <ComboboxList>
            {(client: (typeof clients)[number]) => (
                <ComboboxItem key={client.value} value={client}>
                    {client.label}
                </ComboboxItem>
            )}
        </ComboboxList>
    </ComboboxContent>
</Combobox>;

Several ValuesCopy Anchor Link

To allow several values, set multiple on Combobox. To open the list below the whole field, pass the ref that useComboboxAnchor returns to ComboboxChips and to anchor on ComboboxContent.

import {
    Combobox,
    ComboboxChip,
    ComboboxChips,
    ComboboxChipsInput,
    ComboboxContent,
    ComboboxValue,
    useComboboxAnchor,
} from '@/components/ui/combobox';

const anchor = useComboboxAnchor();

<Combobox items={clients} multiple>
    <ComboboxChips ref={anchor} className="w-80">
        <ComboboxValue>
            {(selected: typeof clients) =>
                selected.map((client) => <ComboboxChip key={client.value}>{client.label}</ComboboxChip>)
            }
        </ComboboxValue>
        <ComboboxChipsInput aria-label="Clients" placeholder="Add a client" />
    </ComboboxChips>
    <ComboboxContent anchor={anchor} />
</Combobox>;

With a Clear ButtonCopy Anchor Link

To show a clear button while a value is set, set showClear on ComboboxInput.

<ComboboxInput aria-label="Client" placeholder="Choose a client" showClear />

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Combobox, where ComboboxContent is Combobox.Popup and ComboboxLabel is Combobox.GroupLabel. See the Base UI Combobox documentation for items, value, onValueChange, multiple, autoHighlight, and filter.

ComboboxInputCopy Anchor Link

ComboboxContentCopy Anchor Link

ComboboxChipCopy Anchor Link