useComboBox

Provides the behavior and accessibility implementation for a combo box component. A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.

Favorite Animal

Example

ComboBox.tsx

DropdownListBox.tsx

ComboBox.css

Form.css

ListBox.css

Popover.css

Example

ComboBox.tsx

DropdownListBox.tsx

ComboBox.css

Form.css

ListBox.css

Popover.css

import {ComboBox, ComboBoxItem} from './ComboBox';

<ComboBox label="Favorite Animal">
  <ComboBoxItem>Aardvark</ComboBoxItem>
  <ComboBoxItem>Cat</ComboBoxItem>
  <ComboBoxItem>Dog</ComboBoxItem>
  <ComboBoxItem>Kangaroo</ComboBoxItem>
  <ComboBoxItem>Panda</ComboBoxItem>
  <ComboBoxItem>Snake</ComboBoxItem>
</ComboBox>

API

<ComboBox>
  <Label />
  <Group>
    <Input />
    <Button />
  </Group>
  <ComboBoxValue />
  <Text slot="description" />
  <FieldError />
  <Popover>
    <ListBox />
  </Popover>
</ComboBox>

useComboBoxState<T, M extends SelectionMode = 'single'>(props: ComboBoxStateOptions<T, M>): ComboBoxState<T, M>

useComboBox<T, M extends SelectionMode = 'single'>(props: AriaComboBoxOptions<T, M>, state: ComboBoxState<T, M>): ComboBoxAria<T>

ComboBoxState

Properties

Name	Type
`selectedItems`	`Node<T>[]`
The value of the selected items.
`focusStrategy`	`FocusStrategy \| null`
Controls which item will be auto focused when the menu opens.
`isFocused`	`boolean`
Whether the select is currently focused.
`collection`	`Collection<Node<T>>`
A collection of items in the list.
`selectionManager`	`SelectionManager`
A selection manager to read and update multiple selection state.
`point`	`Point \| null`
The cursor position when the overlay was triggered, relative to the window viewport.
`realtimeValidation`	`ValidationResult`
Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`
Currently displayed validation results, updated when the user commits their changes.

`disabledKeys`	`Set<Key>`
A set of items that are disabled.

`value`	`ValueType<SelectionMode>`
The current combobox value.
`defaultValue`	`ValueType<SelectionMode>`
The default combobox value.
`inputValue`	`string`
The current value of the combo box input.
`defaultInputValue`	`string`
The default value of the combo box input.

Methods

`setValue(value: Key \| readonly Key[] \| null): void`
Sets the combobox value.
`setInputValue(value: string): void`
Sets the value of the combo box input.
`commit(): void`
Selects the currently focused item and updates the input value.
`setFocused(isFocused: boolean): void`
Sets whether the select is focused.
`open(focusStrategy?: FocusStrategy \| null, trigger?: MenuTriggerAction): void`
Opens the menu.
`toggle(focusStrategy?: FocusStrategy \| null, trigger?: MenuTriggerAction): void`
Toggles the menu.
`revert(): void`
Resets the input value to the previously selected item's text if any and closes the menu.
`setOpen(isOpen: boolean): void`
Sets whether the overlay is open.
`close(): void`
Closes the overlay.
`setPoint(point: Point): void`
Sets the cursor position relative to the window viewport.
`updateValidation(result: ValidationResult): void`
Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`
Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`
Commits the realtime validation so it is displayed to the user.

AriaComboBoxOptions

Name	Type	Default
`inputRef`	`RefObject<HTMLInputElement \| null>`	Default: —
The ref for the input element.
`popoverRef`	`RefObject<Element \| null>`	Default: —
The ref for the list box popover.
`listBoxRef`	`RefObject<HTMLElement \| null>`	Default: —
The ref for the list box.
`buttonRef`	`RefObject<Element \| null>`	Default: —
The ref for the optional list box popup trigger button.
`labelElementType`	`ElementType`	Default: `'label'`
The HTML element used to render the label, e.g. 'label', or 'span'.
`keyboardDelegate`	`KeyboardDelegate`	Default: —
An optional keyboard delegate implementation, to override the default.
`layoutDelegate`	`LayoutDelegate`	Default: —
A delegate object that provides layout information for items in the collection. By default this uses the DOM, but this can be overridden to implement things like virtualized scrolling.
`allowsCustomValue`	`boolean`	Default: —
Whether the ComboBox allows a non-item matching input value to be set.
`menuTrigger`	`MenuTriggerAction`	Default: `'input'`
The interaction required to display the ComboBox menu.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.
`placeholder`	`string`	Default: —
Temporary text that occupies the text input when it is empty.

`items`	`Iterable<T>`	Default: —
The list of ComboBox items (controlled).
`defaultItems`	`Iterable<T>`	Default: —
The list of ComboBox items (uncontrolled).

`selectionMode`	`SelectionMode`	Default: `'single'`
Whether single or multiple selection is enabled.
`disabledKeys`	`Iterable<Key>`	Default: —
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`shouldFocusWrap`	`boolean`	Default: —
Whether keyboard navigation is circular.

`value`	`ValueType<SelectionMode>`	Default: —
The current value (controlled).
`defaultValue`	`ValueType<SelectionMode>`	Default: —
The default value (uncontrolled).
`onChange`	`(value: ChangeValueType<SelectionMode>) => void`	Default: —
Handler that is called when the value changes.
`inputValue`	`string`	Default: —
The value of the ComboBox input (controlled).
`defaultInputValue`	`string`	Default: —
The default value of the ComboBox input (uncontrolled).
`onInputChange`	`(value: string) => void`	Default: —
Handler that is called when the ComboBox input value changes.

ComboBoxAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the label element.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`
Props for the combo box input element.
`listBoxProps`	`<T>`
Props for the list box, to be passed to `useListBox`.
`buttonProps`	`AriaButtonProps`
Props for the optional trigger button, to be passed to `useButton`.
`valueProps`	`DOMAttributes`
Props for the element representing the selected value.
`descriptionProps`	`DOMAttributes`
Props for the combo box description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the combo box error message element, if any.
`validationDetails`	`ValidityState`
The native validation details for the input.