Skip to content

ComboBox

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.

Import

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

Live Editor

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.

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.

Compact Size

Use the compact size for tighter layouts.

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 success, 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.

Props

Visit the Documentation Site for the full list of props.

NameTypeDefaultDescription
compactboolean-Whether the input is compact or not
disableIconAnimationboolean--
iconVariant"search" | "chevron"chevron-
isSuccessboolean--
refRef<HTMLDivElement>-Requires React 19
allowsCustomValueboolean-Whether the ComboBox allows a non-item matching input value to be set.
allowsEmptyCollectionboolean-Whether the combo box allows the menu 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.
autoFocusboolean-Whether the element should receive focus on render.
childrenChildrenOrFunction<ComboBoxRenderProps>-The children of the component. A function may be provided to alter the children based on component state.
classNameClassNameOrFunction<ComboBoxRenderProps>'react-aria-ComboBox'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.
defaultFilter(textValue: string, inputValue: string) => boolean-The filter function used to determine if a option should be included in the combo box list.
defaultInputValuestring-The default value of the ComboBox input (uncontrolled).
defaultItemsIterable<T>-The list of ComboBox items (uncontrolled).
defaultSelectedKeyKey-The initial selected key in the collection (uncontrolled). @deprecated
defaultValueKey-The default value (uncontrolled).
dirstring--
disabledKeysIterable<Key>-The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
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).
formValue"text" | "key"'key'Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted.
hiddenboolean--
idstring-The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inertboolean--
inputValuestring-The value of the ComboBox input (controlled).
isDisabledboolean-Whether the input is disabled.
isInvalidboolean-Whether the input value is invalid.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
isRequiredboolean-Whether user input is required on the input before form submission.
itemsIterable<T>-The list of ComboBox items (controlled).
langstring--
menuTriggerMenuTriggerAction'input'The interaction required to display the ComboBox menu.
namestring-The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
onAnimationEndAnimationEventHandler<HTMLDivElement>--
onAnimationEndCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationIterationAnimationEventHandler<HTMLDivElement>--
onAnimationIterationCaptureAnimationEventHandler<HTMLDivElement>--
onAnimationStartAnimationEventHandler<HTMLDivElement>--
onAnimationStartCaptureAnimationEventHandler<HTMLDivElement>--
onAuxClickMouseEventHandler<HTMLDivElement>--
onAuxClickCaptureMouseEventHandler<HTMLDivElement>--
onBlur(e: FocusEvent<HTMLInputElement, Element>) => void-Handler that is called when the element loses focus.
onChange(value: Key) => void-Handler that is called when the value changes.
onClickMouseEventHandler<HTMLDivElement>--
onClickCaptureMouseEventHandler<HTMLDivElement>--
onContextMenuMouseEventHandler<HTMLDivElement>--
onContextMenuCaptureMouseEventHandler<HTMLDivElement>--
onDoubleClickMouseEventHandler<HTMLDivElement>--
onDoubleClickCaptureMouseEventHandler<HTMLDivElement>--
onFocus(e: FocusEvent<HTMLInputElement, 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>--
onInputChange(value: string) => void-Handler that is called when the ComboBox input value changes.
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, menuTrigger?: MenuTriggerAction) => void-Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
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>--
renderDOMRenderFunction<"div", ComboBoxRenderProps>-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"'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.
shouldFocusWrapboolean-Whether keyboard navigation is circular.
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<ComboBoxRenderProps>-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: ComboBoxValidationValue<"single">) => 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-The current value (controlled).