Skip to content

Select

The Select component provides a way to choose a single value from a list of options. It supports both controlled and uncontrolled usage, dynamic options, and various states like disabled, invalid, and success.

Import

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

Live Editor

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.

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.

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.

Props

Visit the Documentation Site for the full list of props.

NameTypeDefaultDescription
compactbooleanfalseRenders a compact version of the Select
isSuccessboolean--
refRef<HTMLDivElement>-Requires React 19
allowsEmptyCollectionboolean-Whether the select should be allowed to be open when the collection is empty.
aria-describedbystring-Identifies the element (or elements) that describes the object.
aria-detailsstring-Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-labelstring-Defines a string value that labels the current element.
aria-labelledbystring-Identifies the element (or elements) that labels the current element.
autoCompletestring-Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
autoFocusboolean-Whether the element should receive focus on render.
childrenChildrenOrFunction<SelectRenderProps>-The children of the component. A function may be provided to alter the children based on component state.
classNameClassNameOrFunction<SelectRenderProps>'react-aria-Select'The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultOpenboolean-Sets the default open state of the menu.
defaultSelectedKeyKey-The initial selected key in the collection (uncontrolled). @deprecated
defaultValueKey | readonly Key[]-The default value (uncontrolled).
dirstring--
disabledKeysIterable<Key>-The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
excludeFromTabOrderboolean-Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
formstring-The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
hiddenboolean--
idstring-The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inertboolean--
isDisabledboolean-Whether the input is disabled.
isInvalidboolean-Whether the input value is invalid.
isOpenboolean-Sets the open state of the menu.
isRequiredboolean-Whether user input is required on the input before form submission.
langstring--
namestring-The name of the input, used when submitting an HTML form.
onAnimationEndAnimationEventHandler<HTMLDivElement>--
onAnimationEndCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationIterationAnimationEventHandler<HTMLDivElement>--
onAnimationIterationCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationStartAnimationEventHandler<HTMLDivElement>--
onAnimationStartCaptureAnimationEventHandler<HTMLDivElement>--
onAuxClickMouseEventHandler<HTMLDivElement>--
onAuxClickCaptureMouseEventHandler<HTMLDivElement>--
onBlur(e: FocusEvent<Element, Element>) => void-Handler that is called when the element loses focus.
onChange(value: ChangeValueType<M>) => void-Handler that is called when the value changes.
onClickMouseEventHandler<HTMLDivElement>--
onClickCaptureMouseEventHandler<HTMLDivElement>--
onContextMenuMouseEventHandler<HTMLDivElement>--
onContextMenuCaptureMouseEventHandler<HTMLDivElement>--
onDoubleClickMouseEventHandler<HTMLDivElement>--
onDoubleClickCaptureMouseEventHandler<HTMLDivElement>--
onFocus(e: FocusEvent<Element, Element>) => void-Handler that is called when the element receives focus.
onFocusChange(isFocused: boolean) => void-Handler that is called when the element's focus status changes.
onGotPointerCapturePointerEventHandler<HTMLDivElement>--
onGotPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onKeyDown(e: KeyboardEvent) => void-Handler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => void-Handler that is called when a key is released.
onLostPointerCapturePointerEventHandler<HTMLDivElement>--
onLostPointerCaptureCapturePointerEventHandler<HTMLDivElement>--
onMouseDownMouseEventHandler<HTMLDivElement>--
onMouseDownCaptureMouseEventHandler<HTMLDivElement>--
onMouseEnterMouseEventHandler<HTMLDivElement>--
onMouseLeaveMouseEventHandler<HTMLDivElement>--
onMouseMoveMouseEventHandler<HTMLDivElement>--
onMouseMoveCaptureMouseEventHandler<HTMLDivElement>--
onMouseOutMouseEventHandler<HTMLDivElement>--
onMouseOutCaptureMouseEventHandler<HTMLDivElement>--
onMouseOverMouseEventHandler<HTMLDivElement>--
onMouseOverCaptureMouseEventHandler<HTMLDivElement>--
onMouseUpMouseEventHandler<HTMLDivElement>--
onMouseUpCaptureMouseEventHandler<HTMLDivElement>--
onOpenChange(isOpen: boolean) => void-Method that is called when the open state of the menu changes.
onPointerCancelPointerEventHandler<HTMLDivElement>--
onPointerCancelCapturePointerEventHandler<HTMLDivElement>--
onPointerDownPointerEventHandler<HTMLDivElement>--
onPointerDownCapturePointerEventHandler<HTMLDivElement>--
onPointerEnterPointerEventHandler<HTMLDivElement>--
onPointerLeavePointerEventHandler<HTMLDivElement>--
onPointerMovePointerEventHandler<HTMLDivElement>--
onPointerMoveCapturePointerEventHandler<HTMLDivElement>--
onPointerOutPointerEventHandler<HTMLDivElement>--
onPointerOutCapturePointerEventHandler<HTMLDivElement>--
onPointerOverPointerEventHandler<HTMLDivElement>--
onPointerOverCapturePointerEventHandler<HTMLDivElement>--
onPointerUpPointerEventHandler<HTMLDivElement>--
onPointerUpCapturePointerEventHandler<HTMLDivElement>--
onScrollUIEventHandler<HTMLDivElement>--
onScrollCaptureUIEventHandler<HTMLDivElement>--
onSelectionChange(key: Key) => void-Handler that is called when the selection changes. @deprecated
onTouchCancelTouchEventHandler<HTMLDivElement>--
onTouchCancelCaptureTouchEventHandler<HTMLDivElement>--
onTouchEndTouchEventHandler<HTMLDivElement>--
onTouchEndCaptureTouchEventHandler<HTMLDivElement>--
onTouchMoveTouchEventHandler<HTMLDivElement>--
onTouchMoveCaptureTouchEventHandler<HTMLDivElement>--
onTouchStartTouchEventHandler<HTMLDivElement>--
onTouchStartCaptureTouchEventHandler<HTMLDivElement>--
onTransitionCancelTransitionEventHandler<HTMLDivElement>--
onTransitionCancelCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionEndTransitionEventHandler<HTMLDivElement>--
onTransitionEndCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionRunTransitionEventHandler<HTMLDivElement>--
onTransitionRunCaptureTransitionEventHandler<HTMLDivElement>--
onTransitionStartTransitionEventHandler<HTMLDivElement>--
onTransitionStartCaptureTransitionEventHandler<HTMLDivElement>--
onWheelWheelEventHandler<HTMLDivElement>--
onWheelCaptureWheelEventHandler<HTMLDivElement>--
placeholderstring'Select an item' (localized)Temporary text that occupies the select when it is empty.
renderDOMRenderFunction<"div", SelectRenderProps>-Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
selectedKeyKey-The currently selected key in the collection (controlled). @deprecated
selectionMode"single" | "multiple"'single'Whether single or multiple selection is enabled.
shouldFlipbooleantrueWhether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
slotstring-A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
styleStyleOrFunction<SelectRenderProps>-The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate"yes" | "no"--
validate(value: ValidationType<M>) => true | ValidationError-A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior"native" | "aria"'native'Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
valueKey | readonly Key[]-The current value (controlled).