ComboBox

Copy for LLM

A Combobox allows the user to select or search from a list of options by typing in the input or selecting from a list of options. It supports single and multiple selection.

Import

import { ComboBox } from "@cfa/react-core";

Live Editor

Guidelines

When to use

Combobox is for searching or filtering a long predefined list in a form, or entering a custom value that is not in the list.

Do

Show a No results empty state when filtering matches nothing.
When custom values are allowed, show Use "{user_input}" as the first option once typing produces no exact match. Validate the typed value before submission.
For async or remote options, debounce input, show a loading indicator in the listbox while fetching, and cache recent queries on the client.

Avoid

Using Combobox for fewer than three short options people should see at once. Use RadioGroup.
Using Combobox when the list fits Select without search, about 15 or fewer options. Use Select.

Examples

Basic Usage

A simple combobox with a label and items.

Dynamic Items

You can dynamically render items based on an array of data.

Disabled Items

You can disable specific items using the disabledKeys prop.

Default Selected Item

You can set a default selected item using the defaultSelectedKey prop.

Multiple Selection

Set selectionMode="multiple" on Combobox.Root to allow selecting more than one option. The input acts as a search field, and selected values are displayed below using Combobox.Value.

Multiple Selection with Tags

Use the Combobox.Value render prop with TagGroup to display selected items as tags below the input.

With Description

Add helper text below the combobox by using the Combobox.Description component.

Custom Error Messages

Error states can be triggered using the isInvalid prop and the Combobox.Error component for custom messages.

Search Variant

Use the search icon variant for filtering large lists of options.

Sizes

Use the size prop on Combobox.Root to control trigger and list item sizing. Options are sm, md (default), and lg. Pass size="lg" to match the previous default trigger height.

Clear Button

We provide the Combobox.ClearButton component that allows you to have an out of the box experience to allow for reseting the Combobox state.

Normally, you would have to use a controlled version of the component and manually handle the state yourself. This component can be used anywhere, as long as it is nested within the Combobox.Root. Pressing the button will result in the state being reset.

Controlled

Use the defaultValue or value prop to set the selected item. The value corresponds to the id prop of an item.

States

The Combobox supports various states including invalid, disabled, and read-only.

TimePicker

A TimePicker can easily be created using the Combobox component. Just pass in a static array of times or dynamically create an Array using your favorite Date/Time library. With this approach you have the flexibility of structuring your data in a way that makes the most sense for you.

The below example is pretty simple, but you are free to create your times in any way that you want.

Sections / Grouping

Combobox supports using sections to group items. When using sections, it is preferred that you group all of the available options. Leaving some items as “ungrouped” can sometimes cause confusion.