useComboBoxState

Provides state management for a combo box component. Handles building a collection of items from props and manages the option selection state of the combo box. In addition, it tracks the input value, focus state, and other properties of the combo box.

installyarn add react-stately
version3.31.1
usageimport {useComboBoxState} from 'react-stately'

API#


useComboBoxState<T extends object>( (props: ComboBoxStateOptions<T> )): ComboBoxState<T>

Interface#


Properties

NameTypeDescription
inputValuestringThe current value of the combo box input.
focusStrategyFocusStrategyControls which item will be auto focused when the menu opens.
isFocusedbooleanWhether the select is currently focused.
selectedKeyKeyThe key for the currently selected item.
selectedItemNode<T>The value of the currently selected item.
collectionCollection<Node<T>>A collection of items in the list.
disabledKeysSet<Key>A set of items that are disabled.
selectionManagerSelectionManagerA selection manager to read and update multiple selection state.
isOpenbooleanWhether the overlay is currently open.
realtimeValidationValidationResultRealtime validation results, updated as the user edits the value.
displayValidationValidationResultCurrently displayed validation results, updated when the user commits their changes.

Methods

MethodDescription
setInputValue( (value: string )): voidSets the value of the combo box input.
commit(): voidSelects the currently focused item and updates the input value.
open( (focusStrategy?: FocusStrategynull, , trigger?: MenuTriggerAction )): voidOpens the menu.
toggle( (focusStrategy?: FocusStrategynull, , trigger?: MenuTriggerAction )): voidToggles the menu.
revert(): voidResets the input value to the previously selected item's text if any and closes the menu.
setFocused( (isFocused: boolean )): voidSets whether the select is focused.
setSelectedKey( (key: Keynull )): voidSets the selected key.
setOpen( (isOpen: boolean )): voidSets whether the overlay is open.
close(): voidCloses the overlay.
updateValidation( (result: ValidationResult )): voidUpdates the current validation result. Not displayed to the user until commitValidation is called.
resetValidation(): voidResets the displayed validation state to valid when the user resets the form.
commitValidation(): voidCommits the realtime validation so it is displayed to the user.

Example#


See the docs for useComboBox in react-aria for an example of useComboBoxState.