Skip to content

Combo box

Selects one or more options from a list that filters as you type.

combo-box-basic-demo.tsx

Installation

The CLI adds the files, packages, theme variables, and Tailwind plugin that this component uses. Before you run it, set up your project.

Composition

  • ComboBox

    Owns the search and selected value.

    • ComboBoxLabel
    • ComboBoxControl
      • ComboBoxIconOptional

        The input moves its text to make room for the icon.

      • ComboBoxInput
      • ComboBoxTrigger
    • ComboBoxTags

      Use it in multiple selection mode. The default layout includes it.

    • ComboBoxDescription
    • ComboBoxError
    • ComboBoxContent
      • ComboBoxItemRepeats

Described options

Set textValue to the option name for filtering.

Type to filter the list, then select one.
combo-box-demo.tsx

Leading icon

combo-box-icon-demo.tsx

Disabled

combo-box-disabled-demo.tsx

Multiple selection

Design
Research
Select one or more teams. Remove a tag to clear it.
Selected: Design, Research
combo-box-multiple-demo.tsx

Async loading

When you set items, the combo box does not filter them. Filter in your load function. Also install Spinner.

combo-box-async-demo.tsx

Sizes

The list keeps one row height, so options stay easy to touch.

combo-box-sizes-demo.tsx

API reference

vip/ui adds or changes the props below. For all other props, see React Aria ComboBox (opens in a new tab).

ComboBox

size: "xs" | "sm" | "md" | "lg" | "xl" = "lg"
Sets the size of the input and of the trigger. The list keeps one row height.
options: ComboBoxOption[]
Options for the default list layout.
label: string
Label above the input in the default layout.
description: string
Help text below the input in the default layout.
placeholder: string = "Search options"
Input placeholder in the default layout.
selectionMode: "single" | "multiple" = "single"
Set "multiple" to let the user select more than one option. The default layout then shows the selected options as tags. value, defaultValue, and onValueChange work only in single-selection mode. In multiple-selection mode, value and defaultValue take an array of option ids, and onChange receives the new array.
value: string
The selected option id, controlled. Use it only in single-selection mode.
defaultValue: string
The option id that is selected at first, uncontrolled. Use it only in single-selection mode.
onValueChange: (value: string) => void
Receives the selected id in single-selection mode, or an empty string when the selection is cleared.

ComboBoxTags

label: string = "Selected options"
Accessible name for the selected tags.
emptyText: string = "No options selected."
Text shown when no tags are selected.