SelectionManager

An interface for reading and updating multiple selection state.

install	`yarn add react-stately`
version	3.27.1
usage	`import {SelectionManager} from 'react-stately'`

View repository

GitHub

View package

NPM

Introduction#

A SelectionManager provides a generic interface for reading and updating selection and focus state based on a Collection. As discussed in the selection introduction, a selection is represented by a Set of item keys. Focus is represented by a single item key.

Focus state is updated when navigating a collection with the keyboard. Selection state is updated when a user clicks or taps an item, or uses the keyboard to select an item. These interactions are handled by the useSelectableCollection hook in react-aria.

A SelectionManager wraps the state returned by useMultipleSelectionState. Oftentimes, you won't need to construct these directly because hooks like useListState and useTreeState already handle this and return a SelectionManager for you.

Interface#

Properties

Name	Type	Description
`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`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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 )): void`	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> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`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`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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 )): void`	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> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`

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.

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 heirarchy.
`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.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`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.
`props`	`any`	Additional properties specific to a particular node type.

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`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	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, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'selection' | 'all'

'first' | 'last'

Name	Type	Description
`allowsCellSelection`	`boolean`

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.

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.

Handles interactions with selectable collections.

useSelectableCollection(
  (options: AriaSelectableCollectionOptions
)): SelectableCollectionAria

Name	Type	Default	Description
`selectionManager`	`MultipleSelectionManager`	—	An interface for reading and updating multiple selection state.
`keyboardDelegate`	`KeyboardDelegate`	—	A delegate object that implements behavior for keyboard focus movement.
`ref`	`RefObject<HTMLElement>`	—	The ref attached to the element representing the collection.
`autoFocus`	`boolean \| FocusStrategy`	`false`	Whether the collection or one of its items should be automatically focused upon render.
`shouldFocusWrap`	`boolean`	`false`	Whether focus should wrap around when the end/start is reached.
`disallowEmptySelection`	`boolean`	`false`	Whether the collection allows empty selection.
`disallowSelectAll`	`boolean`	`false`	Whether the collection allows the user to select all items via keyboard shortcut.
`selectOnFocus`	`boolean`	`false`	Whether selection should occur automatically on focus.
`disallowTypeAhead`	`boolean`	`false`	Whether typeahead is disabled.
`shouldUseVirtualFocus`	`boolean`	—	Whether the collection items should use virtual focus instead of being focused directly.
`allowsTabNavigation`	`boolean`	—	Whether navigation through tab key is enabled.
`isVirtualized`	`boolean`	—	Whether the collection items are contained in a virtual scroller.
`scrollRef`	`RefObject<HTMLElement>`	—	The ref attached to the scrollable body. Used to provide automatic scrolling on item focus for non-virtualized collections. If not provided, defaults to the collection ref.
`linkBehavior`	`'action' \| 'selection' \| 'override'`	`'action'`	The behavior of links in the collection. - 'action': link behaves like onAction. - 'selection': link follows selection interactions (e.g. if URL drives selection). - 'override': links override all other interactions (link items are not selectable).

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`	The first selected key in the collection.
`lastSelectedKey`	`Key \| null`	The last selected key 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`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.

Methods

Method	Description
`isSelected( (key: Key )): boolean`	Returns whether a key is selected.
`isSelectionEqual( (selection: Set<Key> )): boolean`	Returns whether the current selection is equal to the given selection.
`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`	Toggles, replaces, or extends selection to the given key depending on the pointer event and collection's selection mode.
`canSelectItem( (key: Key )): boolean`	Returns whether the given key can be selected.
`isDisabled( (key: Key )): boolean`	Returns whether the given key is non-interactive, i.e. both selection and actions are disabled.
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`isLink( (key: Key )): boolean`	Returns whether the given key is a hyperlink.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

Method	Description
`getKeyBelow( (key: Key )): Key \| null`	Returns the key visually below the given one, or `null` for none.
`getKeyAbove( (key: Key )): Key \| null`	Returns the key visually above the given one, or `null` for none.
`getKeyLeftOf( (key: Key )): Key \| null`	Returns the key visually to the left of the given one, or `null` for none.
`getKeyRightOf( (key: Key )): Key \| null`	Returns the key visually to the right of the given one, or `null` for none.
`getKeyPageBelow( (key: Key )): Key \| null`	Returns the key visually one page below the given one, or `null` for none.
`getKeyPageAbove( (key: Key )): Key \| null`	Returns the key visually one page above the given one, or `null` for none.
`getFirstKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the first key, or `null` for none.
`getLastKey( (key?: Key, , global?: boolean )): Key \| null`	Returns the last key, or `null` for none.
`getKeyForSearch( (search: string, , fromKey?: Key )): Key \| null`	Returns the next key after `fromKey` that matches the given search string, or `null` for none.

Name	Type	Description
`collectionProps`	`DOMAttributes`	Props for the collection element.

All DOM attributes supported across both HTML and SVG elements.

Extends: AriaAttributes, ReactDOMAttributes

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

Manages state for multiple selection and focus in a collection.

useMultipleSelectionState(
  (props: MultipleSelectionStateProps
)): MultipleSelectionState

Name	Type	Description
`selectionBehavior`	`SelectionBehavior`	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`	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 )) => any`	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	The currently disabled keys in the collection (controlled).

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

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

Name	Type	Description
`filter`	`( (nodes: Iterable<Node<T>> )) => Iterable<Node<T>>`	Filter function to generate a filtered list of nodes.
`collection`	`Collection<Node<T>>`	A pre-constructed collection to use instead of building one from items and children.
`selectionBehavior`	`SelectionBehavior`	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`	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 )) => any`	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	The currently disabled keys in the collection (controlled).

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.

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

useTreeState<T extends object>(
  (props: TreeProps<T>
)): TreeState<T>

Name	Type	Description
`collection`	`Collection<Node<T>>`	A pre-constructed collection to use instead of building one from items and children.
`expandedKeys`	`Iterable<Key>`	The currently expanded keys in the collection (controlled).
`defaultExpandedKeys`	`Iterable<Key>`	The initial expanded keys in the collection (uncontrolled).
`onExpandedChange`	`( (keys: Set<Key> )) => any`	Handler that is called when items are expanded or collapsed.
`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 )) => any`	Handler that is called when the selection changes.
`disabledKeys`	`Iterable<Key>`	The currently disabled keys in the collection (controlled).

Properties

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

Methods

Method	Description
`toggleKey( (key: Key )): void`	Toggles the expanded state for an item by its key.
`setExpandedKeys( (keys: Set<Key> )): void`	Replaces the set of expanded keys.