Select

ReactProps

Github Storybook Markdown Copy for LLM

The Select component provides a way to choose one or more values from a list of options. It supports both controlled and uncontrolled usage, dynamic options, single and multiple selection, and various states like disabled and invalid.

Import

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

Live Editor

Guidelines

When to use

• Select is for picking one option from a closed list that does not need search.

Do

• Order options logically, such as alphabetically, by frequency, or numerically. Use sentence case for option labels.
• Give every option a leading icon, or give none of them one.
• Use a placeholder such as Select, or preselect a common option. Never replace the label with it.
• Always include a visible label. Associate it with a native <label> or aria-labelledby.

Avoid

• Using Select for fewer than three options, or when people benefit from seeing all short options at once. Use RadioGroup.
• Using Select for on/off options. Use Switch.
• Using Select for lists of more than about 15 options. Use Combobox so people can search and filter.
• Using Select for site navigation, sorting, or filtering actions.
• Using Select to switch apps, locations, languages, or other product context. Use Switcher.

Examples

Basic Usage

The most common way to use Select is with static items.

Dynamic Items

Use the items prop with a render function to create options from an array of data.

Sizes

Use the size prop on Select.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.

Disabled Items

Disable specific items in the list by passing an array of keys to the disabledKeys prop.

Default Selected Item

Set the default selected item using the defaultValue prop.

Multiple Selection

Set selectionMode="multiple" on Select.Root to allow selecting more than one option. Use defaultValue or value with an array of item keys. Selected values render as comma-separated text by default, and the menu stays open after each selection so users can continue choosing items.

Multiple Selection with Tags

Use the Select.Value render prop with TagGroup to display selected items as tags. Do not pass onRemove to TagGroup.Root in this pattern.

Note: Dismissible tags are not supported when TagGroup is rendered inside Select.Button. Select.Button renders a <button>, and dismissible tags render their own remove buttons. Nesting buttons is invalid HTML and causes accessibility issues. To remove selections, users can deselect items from the list or use Select.ClearButton. If you need dismissible tags, consider Combobox with selectionMode="multiple" instead, where tags render in Combobox.Value outside the trigger button.

Clear Button

The Select.ClearButton component allows you to have an out of the box experience for reseting the Select 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 Select.Root. Pressing the button will result in the state being reset.

Leading Icon

Add contextual icons to the select button using the leadingIcon prop. This is useful for time pickers, location selectors, or categorized selections where an icon provides visual context.

Note: The leading icon is decorative and marked with aria-hidden="true". It must not convey critical information that isn’t also available in the label or value text.

Validation States

The Select component supports different validation states.

Rich Content

Create complex select items with icons and additional content.

Custom Value Display

Customize how the selected value is displayed using the render function pattern.

Controlled Usage

Control the select’s state from a parent component.

TimePicker

A TimePicker can easily be created using the Select 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

Select 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.