useSelect

Provides the behavior and accessibility implementation for a select component. A select displays a collapsible list of options and allows a user to select one of them.

Favorite Animal

Example

Select.tsx

DropdownListBox.tsx

Select.css

Button.css

Form.css

ListBox.css

Popover.css

Example

Select.tsx

DropdownListBox.tsx

Select.css

Button.css

Form.css

ListBox.css

Popover.css

import {Select, SelectItem} from './Select';

<Select label="Favorite Animal">
  <SelectItem>Aardvark</SelectItem>
  <SelectItem>Cat</SelectItem>
  <SelectItem>Dog</SelectItem>
  <SelectItem>Kangaroo</SelectItem>
  <SelectItem>Panda</SelectItem>
  <SelectItem>Snake</SelectItem>
</Select>

API

useSelectState<T, M extends SelectionMode = 'single'>(props: SelectStateOptions<T, M>): SelectState<T, M>

useSelect<T, M extends SelectionMode = 'single'>(
  props: AriaSelectOptions<T, M>,
state: SelectState<T, M>,
ref: RefObject<HTMLElement | null>
): SelectAria<T, M>

SelectState

Properties

Name	Type
`selectedItems`	`Node<T>[]`
The value of the selected items.
`isFocused`	`boolean`
Whether the select is currently focused.
`focusStrategy`	`FocusStrategy \| null`
Controls which item will be auto focused when the menu opens.
`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 select value.
`defaultValue`	`ValueType<SelectionMode>`
The default select value.

Methods

`setValue(value: Key \| readonly Key[] \| null): void`
Sets the select value.
`setFocused(isFocused: boolean): void`
Sets whether the select is focused.
`open(focusStrategy?: FocusStrategy \| null): void`
Opens the menu.
`toggle(focusStrategy?: FocusStrategy \| null): void`
Toggles 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.

AriaSelectOptions

Name	Type
`keyboardDelegate`	`KeyboardDelegate`
An optional keyboard delegate implementation for type to select, to override the default.
`allowsEmptyCollection`	`boolean`
Whether the select should be allowed to be open when the collection is empty.
`isDisabled`	`boolean`
Whether the input is disabled.
`placeholder`	`string`
Temporary text that occupies the text input when it is empty.

`items`	`Iterable<T>`
Item objects in the collection.

`selectionMode`	`SelectionMode`
Whether single or multiple selection is enabled.
`disabledKeys`	`Iterable<Key>`
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

`value`	`ValueType<SelectionMode>`
The current value (controlled).
`defaultValue`	`ValueType<SelectionMode>`
The default value (uncontrolled).
`onChange`	`(value: ChangeValueType<SelectionMode>) => void`
Handler that is called when the value changes.

SelectAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the label element.
`triggerProps`	`AriaButtonProps`
Props for the popup trigger element.
`valueProps`	`DOMAttributes`
Props for the element representing the selected value.
`menuProps`	`AriaListBoxOptions<T>`
Props for the popup.
`descriptionProps`	`DOMAttributes`
Props for the select's description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the select's error message element, if any.
`hiddenSelectProps`	`HiddenSelectProps<T, SelectionMode>`
Props for the hidden select element.
`validationDetails`	`ValidityState`
The native validation details for the input.