SelectionManager

An interface for reading and updating multiple selection state.

install	`yarn add @react-stately/selection`
version	3.0.0-alpha.1
usage	`import {SelectionManager} from '@react-stately/selection'`

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.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`any`	Whether the selection is empty.
`isSelectAll`	`any`	Whether all items in the collection are selected.

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key )): 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.
`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.

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.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`isEmpty`	`any`	Whether the selection is empty.
`isSelectAll`	`any`	Whether all items in the collection are selected.

Methods

Method	Description
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key )): 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.
`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.

'none' | 'single' | 'multiple'

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

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`	Get an item by 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.

useSelectableCollection(
  (options: SelectableCollectionOptions
)): SelectableCollectionAria

Name	Type	Description
`selectionManager`	`MultipleSelectionManager`
`keyboardDelegate`	`KeyboardDelegate`
`ref`	`RefObject<HTMLElement>`
`autoFocus`	`boolean \| FocusStrategy`
`shouldFocusWrap`	`boolean`
`disallowEmptySelection`	`boolean`
`disallowSelectAll`	`boolean`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`
`disallowEmptySelection`	`boolean`
`selectedKeys`	`Set<Key>`
`isFocused`	`boolean`
`focusedKey`	`Key`

Methods

Method	Description
`extendSelection( (toKey: Key )): void`
`toggleSelection( (key: Key )): void`
`replaceSelection( (key: Key )): void`
`selectAll( ( )): void`
`clearSelection( ( )): void`
`isSelected( (key: Key )): boolean`
`setFocused( (isFocused: boolean )): void`
`setFocusedKey( (key: Key )): void`

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

'first' | 'last'

Name	Type	Description
`collectionProps`	`HTMLAttributes<HTMLElement>`

Manages state for multiple selection and focus in a collection.

useMultipleSelectionState(
  (props: MultipleSelection
)): MultipleSelectionState

Name	Type	Description
`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.

'all' | Set<Key>

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`
`disallowEmptySelection`	`boolean`
`selectedKeys`	`Selection`
`isFocused`	`boolean`
`focusedKey`	`Key`

Methods

Method	Description
`setSelectedKeys( (keys: Selection \| ( (v: Selection )) => Selection )): void`
`setFocused( (isFocused: boolean )): void`
`setFocusedKey( (key: Key )): void`

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

useListState<T>(
  (props: CollectionBase<T> & MultipleSelection
)): ListState<T>

Name	Type	Description
`children`	`CollectionChildren<T>`	The contents of the collection.
`items`	`Iterable<T>`	Item objects in the collection.
`disabledKeys`	`Iterable<Key>`	They item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

CollectionElement<T> | CollectionElement<T>[] | (
  (item: T
)) => CollectionElement<T>

SectionElement<T> | ItemElement<T>

ReactElement<SectionProps<T>>

Name	Type	Description
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`children`	`ItemElement<T> \| ItemElement<T>[] \| ItemRenderer<T>`	Static child items or a function to render children.
`items`	`Iterable<T>`	Item objects in the section.

ReactElement<ItemProps<T>>

Name	Type	Description
`children`	`ReactNode`	Rendered contents of the item or child items.
`title`	`ReactNode`	Rendered contents of the item if `children` contains child items.
`textValue`	`string`	A string representation of the item's contents, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this item.
`childItems`	`Iterable<T>`	A list of child item objects. Used for dynamic collections.
`hasChildItems`	`boolean`	Whether this item has children, even if not loaded yet.

(
  (item: T
)) => ItemElement<T>

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>(
  (props: CollectionBase<T> & Expandable & MultipleSelection
)): TreeState<T>

Name	Type	Description
`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.

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.
`toggleKey`	`( (key: Key )) => void`	Toggles the expanded state for an item by its key.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.