A tree provides users with a way to navigate nested hierarchical information, with support for keyboard navigation and selection.
Vanilla CSS theme
--tint CSS variable used by the Vanilla CSS examples.Content
Tree follows the Collection Components API, accepting both static and dynamic collections. This example shows a dynamic collection, passing a list of objects to the items prop, and a recursive function to render the children.
import {Tree, TreeItem} from './Tree';
import {Collection} from 'react-aria-components';
<Tree
aria-label="Files"
defaultExpandedKeys={[1, 4]}
items={items}
selectionMode="multiple">
{function renderItem(item) {
return (
<TreeItem title={item.title}>
{/* recursively render children */}
<Collection items={item.children}>
{renderItem}
</Collection>
</TreeItem>
);
}}
</Tree>
Asynchronous loading
Use renderEmptyState to display a spinner during initial load. To enable infinite scrolling, render a <TreeLoadMoreItem> at the end of each <TreeItem>. Use whatever data fetching library you prefer – this example uses useAsyncList from react-stately.
import {Tree, TreeItem, TreeLoadMoreItem} from './Tree';
import {ProgressCircle} from './ProgressCircle';
import {Collection, useAsyncList} from 'react-aria-components';
interface Character {
name: string
}
function AsyncLoadingExample() {
return (
<Tree
aria-label="Async loading tree"
style={{height: 300}}
renderEmptyState={() => (
<ProgressCircle isIndeterminate aria-label="Loading..." />
)}>
<TreeItem title="Pokemon">
<Collection items={pokemonList.items}>
{(item) => <TreeItem id={item.name} title={item.name} />}
</Collection>
<TreeLoadMoreItem
onLoadMore={pokemonList.loadMore}
isLoading={pokemonList.loadingState === 'loadingMore'} />
</TreeItem>
<TreeItem title="Star Wars">
<Collection items={starWarsList.items}>
{(item) => <TreeItem id={item.name} title={item.name} />}
</Collection>
<TreeLoadMoreItem
onLoadMore={starWarsList.loadMore}
isLoading={starWarsList.loadingState === 'loadingMore'} />
</TreeItem>
</Tree>
);
}
Links
Use the href prop on a <TreeItem> to create a link. See the framework setup guide to learn how to integrate with your framework. Link interactions vary depending on the selection behavior. See the selection guide for more details.
Empty state
import {Tree} from './Tree';
<Tree
aria-label="Search results"
renderEmptyState={() => 'No results found.'}>
{[]}
</Tree>
Selection and actions
Use the selectionMode prop to enable single or multiple selection. The selected items can be controlled via the selectedKeys prop, matching the id prop of the items. The onAction event handles item actions. Items can be disabled with the isDisabled prop. See the selection guide for more details.
Current selection:
Drag and drop
Tree supports drag and drop interactions when the dragAndDropHooks prop is provided using the useDragAndDrop hook. Users can drop data on the list as a whole, on individual items, insert new items between existing ones, or reorder items. React Aria supports drag and drop via mouse, touch, keyboard, and screen reader interactions. See the drag and drop guide to learn more.
import {Tree, TreeItem} from './Tree';
import {useDragAndDrop, Collection, useTreeData} from 'react-aria-components';
function Example() {
let {dragAndDropHooks} = useDragAndDrop({
getItems: (keys, items: typeof tree.items) => items.map(item => ({'text/plain': item.value.title})),
onMove(e) {
if (e.target.dropPosition === 'before') {
tree.moveBefore(e.target.key, e.keys);
} else if (e.target.dropPosition === 'after') {
tree.moveAfter(e.target.key, e.keys);
} else if (e.target.dropPosition === 'on') {
// Move items to become children of the target
let targetNode = tree.getItem(e.target.key);
if (targetNode) {
let targetIndex = targetNode.children ? targetNode.children.length : 0;
let keyArray = Array.from(e.keys);
for (let i = 0; i < keyArray.length; i++) {
tree.move(keyArray[i], e.target.key, targetIndex + i);
}
}
}
}
});
return (
<Tree
aria-label="Tree with hierarchical drag and drop"
selectionMode="multiple"
items={tree.items}
dragAndDropHooks={dragAndDropHooks}
>
{function renderItem(item) {
return (
<TreeItem title={item.value.title}>
{item.children && <Collection items={item.children}>
{renderItem}
</Collection>}
</TreeItem>
)
}}
</Tree>
);
}
Examples
API
<Tree>
<TreeItem>
<TreeItemContent>
<Button slot="chevron" />
<Checkbox slot="selection" /> or <SelectionIndicator />
<Button slot="drag" />
</TreeItemContent>
<TreeItem>
{/* ... */}
</TreeItem>
<TreeLoadMoreItem />
</TreeItem>
</Tree>
Tree
A tree provides users with a way to navigate nested hierarchical information, with support for keyboard navigation and selection.
| Name | Type | |
|---|---|---|
dragAndDropHooks | DragAndDropHooks | |
The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the Tree. | ||
expandedKeys | Iterable | |
| The currently expanded keys in the collection (controlled). | ||
defaultExpandedKeys | Iterable | |
| The initial expanded keys in the collection (uncontrolled). | ||
children | ReactNode | | |
| The contents of the collection. | ||
items | Iterable | |
| Item objects in the collection. | ||
renderEmptyState | | |
| Provides content to display when there are no items in the list. | ||
dependencies | ReadonlyArray | |
| Values that should invalidate the item cache when using dynamic collections. | ||
selectionMode | SelectionMode | |
| The type of selection that is allowed in the collection. | ||
selectionBehavior | SelectionBehavior | |
| How multiple selection should behave in the tree. | ||
selectedKeys | 'all' | Iterable | |
| The currently selected keys in the collection (controlled). | ||
defaultSelectedKeys | 'all' | Iterable | |
| The initial selected keys in the collection (uncontrolled). | ||
onSelectionChange | | |
| Handler that is called when the selection changes. | ||
disabledKeys | Iterable | |
| The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. | ||
disabledBehavior | DisabledBehavior | |
Whether disabledKeys applies to all interactions, or only selection. | ||
disallowEmptySelection | boolean | |
| Whether the collection allows empty selection. | ||
shouldSelectOnPressUp | boolean | |
| Whether selection should occur on press up instead of press down. | ||
escapeKeyBehavior | 'clearSelection' | 'none' | |
| Whether pressing the escape key should clear selection in the grid list or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually. | ||
Default className: react-aria-Tree
| Render Prop | CSS Selector |
|---|---|
isEmpty | CSS Selector: [data-empty]
|
| Whether the tree has no items and should display its empty state. | |
isFocused | CSS Selector: [data-focused]
|
| Whether the tree is currently focused. | |
isFocusVisible | CSS Selector: [data-focus-visible]
|
| Whether the tree is currently keyboard focused. | |
selectionMode | CSS Selector: [data-selection-mode="single | multiple"]
|
| The type of selection that is allowed in the collection. | |
allowsDragging | CSS Selector: [data-allows-dragging]
|
| Whether the tree allows dragging. | |
state | CSS Selector: — |
| State of the tree. | |
TreeItem
A TreeItem represents an individual item in a Tree.
| Name | Type | |
|---|---|---|
id | Key | |
| The unique id of the tree row. | ||
value | object | |
| The object value that this tree item represents. When using dynamic collections, this is set automatically. | ||
textValue | string | |
| A string representation of the tree item's contents, used for features like typeahead. | ||
children | ReactNode | |
| The content of the tree item along with any nested children. Supports static nested tree items or use of a Collection to dynamically render nested tree items. | ||
isDisabled | boolean | |
| Whether the item is disabled. | ||
hasChildItems | boolean | |
| Whether this item has children, even if not loaded yet. | ||
Default className: react-aria-TreeItem
| Render Prop | CSS Selector |
|---|---|
isExpanded | CSS Selector: [data-expanded]
|
| Whether the tree item is expanded. | |
hasChildItems | CSS Selector: [data-has-child-items]
|
| Whether the tree item has child tree items. | |
level | CSS Selector: [data-level="number"]
|
| What level the tree item has within the tree. | |
isFocusVisibleWithin | CSS Selector: [data-focus-visible-within]
|
| Whether the tree item's children have keyboard focus. | |
state | CSS Selector: — |
| The state of the tree. | |
id | CSS Selector: — |
| The unique id of the tree row. | |
isHovered | CSS Selector: [data-hovered]
|
| Whether the item is currently hovered with a mouse. | |
isPressed | CSS Selector: [data-pressed]
|
| Whether the item is currently in a pressed state. | |
isSelected | CSS Selector: [data-selected]
|
| Whether the item is currently selected. | |
isFocused | CSS Selector: [data-focused]
|
| Whether the item is currently focused. | |
isFocusVisible | CSS Selector: [data-focus-visible]
|
| Whether the item is currently keyboard focused. | |
isDisabled | CSS Selector: [data-disabled]
|
Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may
not be focused. Dependent on disabledKeys and disabledBehavior. | |
selectionMode | CSS Selector: [data-selection-mode="single | multiple"]
|
| The type of selection that is allowed in the collection. | |
selectionBehavior | CSS Selector: — |
| The selection behavior for the collection. | |
| CSS Variable |
|---|
--tree-item-level |
| The depth of the item within the tree. Useful to calculate indentation. |
TreeItemContent
| Name | Type | |
|---|---|---|
children | ChildrenOrFunction | |
| The children of the component. A function may be provided to alter the children based on component state. | ||
TreeLoadMoreItem
| Name | Type | Default |
|---|---|---|
children | ChildrenOrFunction | Default: — |
| The load more spinner to render when loading additional items. | ||
isLoading | boolean | Default: — |
| Whether or not the loading spinner should be rendered or not. | ||
scrollOffset | number | Default: 1
|
| The amount of offset from the bottom of your scrollable region that should trigger load more. Uses a percentage value relative to the scroll body's client height. Load more is then triggered when your current scroll position's distance from the bottom of the currently loaded list of items is less than or equal to the provided value. (e.g. 1 = 100% of the scroll region's height). | ||
onLoadMore | | Default: — |
| Handler that is called when more items should be loaded, e.g. while scrolling near the bottom. | ||
Default className: react-aria-TreeLoadMoreItem
| Render Prop | CSS Selector |
|---|---|
level | CSS Selector: [data-level]
|
| What level the tree item has within the tree. | |
| CSS Variable |
|---|
--tree-item-level |
| The depth of the item within the tree. Useful to calculate indentation. |