useTreeState

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

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

View repository

GitHub

View package

NPM

API#

useTreeState<T>(props: CollectionBase<T> & Expandable & MultipleSelection): TreeState<T>

Interface#

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.

Example#

See the docs for useMenu in react-aria for an example of useTreeState.

Name	Type	Description
`children`	`ReactElement<SectionProps<T>> \| ReactElement<ItemProps<T>> \| ReactElement<SectionProps<T>> \| ReactElement<ItemProps<T>>[] \| (item: T) => ReactElement<SectionProps<T>> \| ReactElement<ItemProps<T>>`	The contents of the collection.
`disabledKeys`	`Iterable<Key>`	They item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`items`	`Iterable<T>`	Item objects in the collection or section.
`itemKey`	`string`	Property name on each item object to use as the unique key. `id` or `key` by default.
`isLoading`	`boolean`	Whether the items are currently loading.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.

Name	Type	Description
`title`	`ReactNode`	Rendered contents of the section, e.g. a header.
`aria-label`	`string`	An accessibility label for the section.
`children`	`ReactElement<ItemProps<T>> \| ReactElement<ItemProps<T>>[] \| (item: T) => ReactElement<ItemProps<T>>`	Static child items or a function to render children.
`uniqueKey`	`Key`	A unique key for the section.
`items`	`Iterable<T>`	Item objects in the collection or section.
`itemKey`	`string`	Property name on each item object to use as the unique key. `id` or `key` by default.
`isLoading`	`boolean`	Whether the items are currently loading.
`onLoadMore`	`() => any`	Handler that is called when more items should be loaded, e.g. while scrolling near the bottom.

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.
`uniqueKey`	`Key`	A unique key for this item.

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

'none' | 'single' | 'multiple'

'all' | Set<Key>

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.

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.

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.