Combobox

Installation

The component is exported from @by/experience-system. Add the package with your package manager:

pnpm add @by/experience-system

In this monorepo, depend on the workspace package (for example via workspace:* or your catalog) so imports resolve to packages/experience-system.

Composition

Simple

A single-line input and a flat list.

Combobox
├── ComboboxInput
└── ComboboxContent
    ├── ComboboxEmpty
    └── ComboboxList
        ├── ComboboxItem
        └── ComboboxItem

ComboboxTrigger is rendered inside ComboboxInput by default, and ComboboxClear is optional via showClear.

With chips

Multi-select with multiple, chips, and a chips input.

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

With groups and collection

Nested items per group using ComboboxCollection inside each ComboboxGroup, with separators between groups.

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

Usage

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from '@by/experience-system';

Combobox is a client component ('use client' in the package). Use it inside a Client Component when using the Next.js App Router.

const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'];

<Combobox items={frameworks}>
  <ComboboxInput placeholder="Select a framework..." />
  <ComboboxContent>
    <ComboboxEmpty>No framework found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>;

Examples

Basic

Single-select combobox with filterable options.

Multiple

Use multiple with chips to select more than one value.

Clear button

Set showClear on ComboboxInput to render a clear action.

Groups

Use ComboboxGroup, ComboboxLabel, and ComboboxCollection for grouped options.

Custom items

Provide object items and map display/submission values with itemToStringValue.

API Reference

The API mirrors Base UI Combobox, with Experience System styling and field-surface extensions (size, appearance, showTrigger, showClear, and read-only behavior).

Combobox

Maps to Base UI Combobox.Root.

ComboboxInput

Maps to Base UI Combobox.Input, rendered in an InputGroup surface.

ComboboxContent

Combines Base UI Combobox.Positioner + Combobox.Popup.

ComboboxList

Maps to Base UI Combobox.List.

ComboboxItem

Maps to Base UI Combobox.Item.

ComboboxGroup

Maps to Base UI Combobox.Group.

ComboboxLabel

Maps to Base UI Combobox.GroupLabel.

ComboboxCollection

Maps to Base UI Combobox.Collection.

ComboboxEmpty

Maps to Base UI Combobox.Empty.

ComboboxSeparator

Maps to Base UI Combobox.Separator.

ComboboxChips

Maps to Base UI Combobox.Chips with Experience System field-surface options.

ComboboxChip

Maps to Base UI Combobox.Chip with optional remove action.

ComboboxChipsInput

Maps to Base UI Combobox.Input for multiple mode.

ComboboxTrigger

Maps to Base UI Combobox.Trigger.

ComboboxValue

Maps to Base UI Combobox.Value.

Accessibility

Provide an accessible name for the form control (ComboboxInput with label/htmlFor, or aria-label when needed), and keep empty/status content mounted so assistive technologies announce filtering updates correctly. Group labels (ComboboxLabel) and chips remove actions should use clear text labels.

Keyboard interactions

See Base UI Combobox accessibility guidance and shadcn/ui Combobox composition examples.

Source in the repo: packages/experience-system/src/components/Combobox/Combobox.tsx. Agent-oriented contracts: packages/experience-system/src/components/Combobox/Combobox.instructions.md.