Combobox

A select that filters as you type, with one or many values.

Base UI ComboboxSource

Single value

The user types to filter the list. A click on the input opens the list. Clear removes the value. Empty shows when no item matches.

Multiple values with chips

Use multiple when the user picks several values. Set multiple on Root. Selected items show as chips that wrap with the input.

Sizes

Match the size of the buttons beside the field, and use lg only for a hero field. sm, md, and lg are 26, 36, and 44 pixels high.

sm · dense UI
md · default
lg · hero field

States

Use inset by default and line for light or inline editing, with one appearance per form. Hover and focus the fields to see those states.

inset · forms
Data warehouse is not on this plan.
line · inline editing
Data warehouse is not on this plan.

Usage

These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.

  • Choose the input from the number of options and what the user picks.
    ComponentUse it for
    RadioOne choice from 2 or 3 options that stay visible.
    SelectOne choice from 4 to about 10 options, or fewer options when space is tight.
    ComboboxOne or more choices from a long list, with typing to filter.
    AutocompleteFree text, with suggestions that the user can ignore.
    ChoiceboxA choice where each option needs a description, such as a plan.
    CheckboxAn on or off value in a form that the user submits.
    SwitchA setting that applies at once.
  • Put Empty next to List inside Popup, not in the list.
  • Name each ChipRemove after its chip, for example "Remove Session replay".

API

Props that the library adds. Every part also takes all the Base UI props.

Combobox.InputGroup

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Sets the text size, padding, and control height.
appearance'inset' | 'line''inset'Sets the field shape. Keep inset for forms. Use line for light or inline editing, such as renaming in place, filters, and quick settings.

Combobox.Clear

PropTypeDefaultDescription
aria-labelstring'Clear'The accessible name of the clear button.

Combobox.ChipRemove

PropTypeDefaultDescription
aria-labelstring'Remove'The accessible name of the remove button. Name the chip in it, for example `Remove ${product}`.

Combobox.Empty

PropTypeDefaultDescription
childrenReactNode'No results'The message when no item matches the input.

Combobox.Popup

PropTypeDefaultDescription
sideOffsetnumber4The gap between the input and the popup, in pixels.
containerHTMLElement | ShadowRoot | RefObject | null–The element that the popup renders into. The default is the document body.