Combobox

A combobox is a list of values that people narrow down by typing. raft-ui gives it as parts: a filter that opens a list with a search row, a field that people type into, or a field of chips for several values. For a ready-made field driven by an array of options, use ComboboxSelect.

When to use

The full choice between pickers is in Choosing a component.

Anatomy

• Combobox: the root. Holds the value, the typed text and the open state. Required.
• What opens the list, one of:
  • ComboboxTrigger: the filter button, with an icon, a label, ComboboxTriggerCount and ComboboxTriggerIndicator;
  • ComboboxControl: a field at the control height (44px on a phone, 32px on a desktop) with an ink border, holding ComboboxInput, ComboboxClear and ComboboxTriggerIndicator;
  • ComboboxChips: a field at least the control height, holding one ComboboxChip per chosen value, each with a ComboboxChipRemove, then ComboboxInput.
• ComboboxContent: the popup. Required.
• ComboboxHeader: the popup's top row, with ComboboxLabel and a ComboboxClear. ComboboxSeparator is the hairline under it.
• ComboboxInputGroup: the search row at the top of the list, holding ComboboxInput.
• ComboboxList: the scrolling list of ComboboxItems, each with a ComboboxItemIndicator (the check mark). ComboboxGroup and ComboboxGroupLabel group them; ComboboxRow and ComboboxCollection lay out grids and nested collections.
• ComboboxEmpty: the line shown when nothing matches.
• ComboboxValue, ComboboxPortal, ComboboxPopup: lower-level parts.

Variants

States

• Applied filter: a ComboboxTrigger with a value fills with info-soft and shows the count.
• No match: ComboboxEmpty says what found nothing: No one matches "zz".
• Focus: a chips field rings as a whole (States); the search row in the popup takes the inset ink outline (Elevation).

Behavior

• Filter the list as people type.
• Show ComboboxEmpty when nothing matches. Never leave an empty popup open.
• With multiple, keep the list open when a value is chosen. Clicking outside or Esc closes it.
• Make a chosen value a chip on fill-muted, with a remove button at its end. Typing continues after the last chip.
• A chip sits 6px inside the field's outer edge and 6px from the next one, so it is 20px on a desktop and 32px on a phone and the field keeps the control height until the chips wrap. It wears radius-chip, like every chip; its remove button wears radius-sticker 2px inside the chip, and its focus ring is drawn inside it, where the chip would clip one outside. The clear button in a field is 6px from the field's end, with radius-chip (Shape).
• Put a chip's text in an element of its own (a <span>): a long value truncates there, at the width of the field, with its whole text as the chip's title, and the remove button stays visible (Forms).
• An item is as tall as its content: one line is 36px, and each further line adds only its own height, with the same space above and below the text (Forms).
• A long item wraps onto as many lines as it needs. The list grows to fit it up to 24rem (or the field's width, when that is wider), never past the screen less 8px on each side.
• For results that come from a server, pass filter={null} so the list shows them as they are, and keep the typed text controlled.

Accessibility

Combobox wraps Base UI Combobox: a text input with role="combobox" that controls a listbox, with arrow-key navigation and the highlighted item announced.

• Name the input: with a FieldLabel (Field), or with aria-label on a search row in a popup (Search Channels).
• In a chips field, each chip's remove button and the input are reachable with the keyboard. Name each remove button after its value (Remove Bugen).
• Give ComboboxClear a label that says what it clears when it shows only an icon.