Spectrum 2 is now available! Check out the migration docs.

useMultipleSelectionState

Manages state for multiple selection and focus in a collection.

install	`yarn add react-stately`
version	3.47.0
usage	`import {useMultipleSelectionState} from 'react-stately'`

View repository

GitHub

View package

NPM

Introduction#

useMultipleSelectionState manages selection state for many components. Oftentimes, you won't need to use this hook directly, since it's included in hooks like useListState, and useSelectState. These expose a SelectionManager, which provides a higher level way to manipulate selection state.

API#

useMultipleSelectionState(
  (props: MultipleSelectionStateProps
)): MultipleSelectionState

Interface#

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

Provides state management for list-like components. Handles building a collection of items from props, and manages multiple selection state.

useListState<T>(
  (props: ListProps<T>
)): ListState<T>

Name	Type	Default	Description
`filter`	`( (nodes: Iterable<Node<T>> )) => Iterable<Node<T>>`	—	Filter function to generate a filtered list of nodes.
`layoutDelegate`	`LayoutDelegate`	—	A delegate object that provides layout information for items in the collection. This can be used to override the behavior of shift selection.
`collection`	`Collection<Node<T>>`	—	A pre-constructed collection to use instead of building one from items and children.
`selectionBehavior`	`SelectionBehavior`	`'toggle'`	How multiple selection should behave in the collection.
`allowDuplicateSelectionEvents`	`boolean`	—	Whether onSelectionChange should fire even if the new set of keys is the same as the last.
`disabledBehavior`	`DisabledBehavior`	`'all'`	Whether `disabledKeys` applies to all interactions, or only selection.
`selectionMode`	`SelectionMode`	—	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	—	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	—	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => void`	—	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	—	The currently disabled keys in the collection (controlled).

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`index`	`number`	The index of this node within its parent.
`aria-label`	`string`	An accessibility label for this node.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`firstChildKey`	`Key \| null`	The first child key of this node.
`lastChildKey`	`Key \| null`	The last child key of this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

Name	Type	Description
`x`	`number`
`y`	`number`
`width`	`number`
`height`	`number`

Name	Type	Description
`width`	`number`
`height`	`number`

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.
`filter( (filterFn: ( (nodeValue: string, , node: T )) => boolean )): Collection<T>`	Filters the collection using the given function.

'toggle' | 'replace'

'selection' | 'all'

'none'
  | 'single'
  | 'multiple'

'all' | Set<Key>

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

string | number

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`collection`	`Collection<Node<unknown>>`
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , childFocusStrategy?: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): boolean`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): boolean`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): boolean`
`isDisabled( (key: Key )): boolean`
`isLink( (key: Key )): boolean`
`getItemProps( (key: Key )): any`
`withCollection( (collection: Collection<Node<unknown>> )): SelectionManager`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key \| null`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy \| null`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'first' | 'last'

Name	Type	Description
`allowsCellSelection`	`boolean`
`layoutDelegate`	`LayoutDelegate`
`fullCollection`	`Collection<Node<unknown>>`

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.
`key`	`string`	The key that triggered the press event, if it was triggered by a keyboard interaction. This is useful for differentiating between Space and Enter key presses.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.
`key`	`string`	The key that triggered the press event, if it was triggered by a keyboard interaction. This is useful for differentiating between Space and Enter key presses.

Provides state management for a select component. Handles building a collection of items from props, handles the open state for the popup menu, and manages multiple selection state.

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

Name	Type	Default	Description
`selectionMode`	`SelectionMode`	`'single'`	Whether single or multiple selection is enabled.
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Method that is called when the open state of the menu changes.
`shouldCloseOnSelect`	`boolean`	—	Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise.
`allowsEmptyCollection`	`boolean`	—	Whether the select should be allowed to be open when the collection is empty.
`items`	`Iterable<T>`	—	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`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.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	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.
`validate`	`( (value: ValidationType<SelectionMode> )) => ValidationError \| true \| null \| undefined`	—	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.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`label`	`ReactNode`	—	The content to display as the label.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status 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.
`collection`	`Collection<Node<T>>`	—	A pre-constructed collection to use instead of building one from items and children.

'single' | 'multiple'

SelectionMode extends 'single' ? Key | null : readonly Key[]

SelectionMode extends 'single' ? Key | null : Key[]

'valid' | 'invalid'

SelectionMode extends 'single' ? Key : Key[]

string | string[]

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Properties

Name	Type	Description
`value`	`ValueType<SelectionMode>`	The current select value.
`defaultValue`	`ValueType<SelectionMode>`	The default select value.
`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.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.
`isOpen`	`boolean`	Whether the overlay is currently open.
`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.

Methods

Method	Description
`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.
`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.

Name	Type	Default	Description
`selectionBehavior`	`SelectionBehavior`	`'toggle'`	How multiple selection should behave in the collection.
`allowDuplicateSelectionEvents`	`boolean`	—	Whether onSelectionChange should fire even if the new set of keys is the same as the last.
`disabledBehavior`	`DisabledBehavior`	`'all'`	Whether `disabledKeys` applies to all interactions, or only selection.
`selectionMode`	`SelectionMode`	—	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKeys`	`'all' \| Iterable<Key>`	—	The currently selected keys in the collection (controlled).
`defaultSelectedKeys`	`'all' \| Iterable<Key>`	—	The initial selected keys in the collection (uncontrolled).
`onSelectionChange`	`( (keys: Selection )) => void`	—	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	—	The currently disabled keys in the collection (controlled).