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.
npm
yarn
pnpm
bun
Composition
ComboBoxOwns the search and selected value.
ComboBoxLabelComboBoxControlComboBoxIconOptionalThe input moves its text to make room for the icon.
ComboBoxInputComboBoxTrigger
ComboBoxTagsUse it in multiple selection mode. The default layout includes it.
ComboBoxDescriptionComboBoxErrorComboBoxContentComboBoxItemRepeats
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
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.