Combobox

Installation

npx @yolkui/cli add combobox

Usage

Pass the options to Combobox as items ({ label, value }) and render each one from ComboboxList as a ComboboxItem: typing filters the list, Base UI matches on the label. The field is Input's surface, with its sizes and shape="pill"; the list is Select's, the chosen item checked at the end. While there is a value, an × before the chevron empties the field; showClear={false} or showTrigger={false} on ComboboxInput leaves either out.

• For a short, fixed list where nobody types, Select is simpler: it opens on the chosen item and needs no filtering.
• ComboboxEmpty shows when nothing matches; Base UI announces it to screen readers.

Several values

With multiple, each value is a chip in ComboboxChips, with its own × to remove it; chips wrap onto new rows and the field grows. The dashed + button after them (ComboboxChipsTrigger) opens the list, and ComboboxSearch at the list's top takes the typing. Its placeholder ("Select") shows inside it while nothing is chosen, and starts its name meanwhile ("Select Frameworks"), so the visible text is in the name; the label still names it on its own. The list stays open while you pick, and the form sends every value chosen.

• From the + button, the Left arrow moves into the chips (Right in a right-to-left layout); Backspace or Delete removes the focused chip.
• Name the chips with aria-label on ComboboxChips ("Selected frameworks"): they are a toolbar. While there are chips, the + button tells a screen reader how many and how to reach them ("2 selected. Press Left Arrow to reach them.").
• The strings are English by default: removeLabel and aria-description on ComboboxChip, formatChipsDescription on ComboboxChipsTrigger translate them.
• A text field among the chips, as in shadcn's examples, is ComboboxChipsInput: it still works, and Backspace in it removes the last chip.

Groups

Pass groups ({ value, items }) as items and render each with ComboboxGroup, a ComboboxLabel and a ComboboxCollection of its items, so a filtered list keeps every label above its matches. ComboboxSeparator draws a line between groups.

Invalid

aria-invalid on ComboboxInput (or an invalid Field) turns the edge and the focus outline red, and FieldError says why, with an icon and words.

Disabled

A disabled combobox is a disabled text field: it fades, is skipped by Tab and is left out of the form, as Input. Say why in a FieldDescription.

Read-only

readOnly on Combobox shows the value at full strength and sends it with the form, but nothing changes it: the field has no × and no chevron, chips lose their ×, and the list never opens. There is nothing to add, so the + is not drawn, but the field keeps one Tab stop with its focus outline, as a read-only input does: a screen reader hears it is read-only and how many are chosen, and the Left Arrow reaches the chips. Say who can change it in a FieldDescription.

Accessibility

The field is a combobox and the list a listbox. Typing opens and filters it, the Down and Up arrows move through it, Enter picks the highlighted item and Escape closes the list. Screen readers hear the label, the value and how many results match.

• Give it a label: a FieldLabel in a Field, or aria-label on ComboboxInput when it stands alone. With chips the + button is the field's control: a FieldLabel names it, or an aria-label ("Add framework") outside a Field. Name the search field and the list too.
• The × and the chevron are left out of the Tab order (Base UI's): from the keyboard, select the text and delete it, or open the list with the Down arrow.
• The chosen item is marked with a check, never colour alone.