useTreeData
Manages state for an immutable tree data structure, and provides convenience methods to update the data over time.
install | yarn add react-stately |
---|---|
version | 3.32.2 |
usage | import {useTreeData} from 'react-stately' |
Introduction#
React requires all data structures passed as props to be immutable. This enables them to be diffed correctly to determine what has changed since the last render. This can be challenging to accomplish from scratch in a performant way in JavaScript.
useTreeData
helps manage an immutable tree data structure, with helper methods to update the data in an efficient way.
Since the data is stored in React state, calling these methods to update the data automatically causes the component
to re-render accordingly.
In addition, useTreeData
stores selection state for the tree, based on unique item keys. This can be updated programmatically,
and is automatically updated when items are removed from the tree.
API#
useTreeData<T extends object>(
(options: TreeOptions<T>
)): TreeData<T>
Options#
Name | Type | Description |
initialItems | object[] | Initial root items in the tree. |
initialSelectedKeys | Iterable<Key> | The keys for the initially selected items. |
getKey | (
(item: object
)) => Key | A function that returns a unique key for an item object. |
getChildren | (
(item: object
)) => object[] | A function that returns the children for an item object. |
Interface#
Properties
Name | Type | Description |
items | TreeNode<object>[] | The root nodes in the tree. |
selectedKeys | Set<Key> | The keys of the currently selected items in the tree. |
Methods
Method | Description |
setSelectedKeys(
(keys: Set<Key>
)): void | Sets the selected keys. |
getItem(
(key: Key
)): TreeNode<object> | Gets a node from the tree by key. |
insert(
parentKey: Key
| | null,
index: number,
...values: object[]
): void | Inserts an item into a parent node as a child. |
insertBefore(
(key: Key,
, ...values: object[]
)): void | Inserts items into the list before the item at the given key. |
insertAfter(
(key: Key,
, ...values: object[]
)): void | Inserts items into the list after the item at the given key. |
append(
(parentKey: Key
| | null,
, ...values: object[]
)): void | Appends an item into a parent node as a child. |
prepend(
(parentKey: Key
| | null,
, ...value: object[]
)): void | Prepends an item into a parent node as a child. |
remove(
(...keys: Key[]
)): void | Removes an item from the tree by its key. |
removeSelectedItems(): void | Removes all items from the tree that are currently in the set of selected items. |
move(
key: Key,
toParentKey: Key
| | null,
index: number
): void | Moves an item within the tree. |
update(
(key: Key,
, newValue: object
)): void | Updates an item in the tree. |
Example#
To construct a tree, pass an initial set of items along with functions to get a key for each item, and its children.
useTreeData
processes these items into nodes, which you can use to render a collection component.
Each node has key
, value
, and children
properties.
This example renders a ListBox
with two sections, each with three child items. It uses the name
property of each item
as the unique key for that item, and the items
property as the children. In addition, it manages the selection state
for the listbox, which will automatically be updated when items are removed from the tree.
interface Iitem {
name: string;
items?: Array<Iitem>;
}
let tree = useTreeData<Iitem>({
initialItems: [
{
name: 'People',
items: [
{name: 'David'},
{name: 'Sam'},
{name: 'Jane'}
]
},
{
name: 'Animals',
items: [
{name: 'Aardvark'},
{name: 'Kangaroo'},
{name: 'Snake'}
]
}
],
initialSelectedKeys: ['Sam', 'Kangaroo'],
getKey: item => item.name,
getChildren: item => item.items || []
});
<ListBox
aria-label="List organisms"
items={tree.items}
selectionMode="multiple"
selectedKeys={tree.selectedKeys}
onSelectionChange={(keys) => {
if (keys !== 'all') {
tree.setSelectedKeys(keys);
}
}}>
{node =>
<Section title={node.value.name} items={node.children}>
{node => <Item>{node.value.name}</Item>}
</Section>
}
</ListBox>
interface Iitem {
name: string;
items?: Array<Iitem>;
}
let tree = useTreeData<Iitem>({
initialItems: [
{
name: 'People',
items: [
{name: 'David'},
{name: 'Sam'},
{name: 'Jane'}
]
},
{
name: 'Animals',
items: [
{name: 'Aardvark'},
{name: 'Kangaroo'},
{name: 'Snake'}
]
}
],
initialSelectedKeys: ['Sam', 'Kangaroo'],
getKey: item => item.name,
getChildren: item => item.items || []
});
<ListBox
aria-label="List organisms"
items={tree.items}
selectionMode="multiple"
selectedKeys={tree.selectedKeys}
onSelectionChange={(keys) => {
if (keys !== 'all') {
tree.setSelectedKeys(keys);
}
}}>
{node =>
<Section title={node.value.name} items={node.children}>
{node => <Item>{node.value.name}</Item>}
</Section>
}
</ListBox>
interface Iitem {
name: string;
items?: Array<Iitem>;
}
let tree = useTreeData<
Iitem
>({
initialItems: [
{
name: 'People',
items: [
{
name: 'David'
},
{ name: 'Sam' },
{ name: 'Jane' }
]
},
{
name: 'Animals',
items: [
{
name:
'Aardvark'
},
{
name:
'Kangaroo'
},
{ name: 'Snake' }
]
}
],
initialSelectedKeys: [
'Sam',
'Kangaroo'
],
getKey: (item) =>
item.name,
getChildren: (item) =>
item.items || []
});
<ListBox
aria-label="List organisms"
items={tree.items}
selectionMode="multiple"
selectedKeys={tree
.selectedKeys}
onSelectionChange={(
keys
) => {
if (
keys !== 'all'
) {
tree
.setSelectedKeys(
keys
);
}
}}
>
{(node) => (
<Section
title={node.value
.name}
items={node
.children}
>
{(node) => (
<Item>
{node.value
.name}
</Item>
)}
</Section>
)}
</ListBox>
Inserting items#
To insert a new item into the tree, use the insert
method or use one of the other convenience methods.
Pass a parentKey
to insert into, or null
to insert a root item.
// Insert an item into the root, after 'People'
tree.insert(null, 1, {name: 'Plants'});
// Insert an item into the 'People' node, after 'David'
tree.insert('People', 1, {name: 'Judy'});
// Insert an item into the root, after 'People'
tree.insert(null, 1, {name: 'Plants'});
// Insert an item into the 'People' node, after 'David'
tree.insert('People', 1, {name: 'Judy'});
// Insert an item into the root, after 'People'
tree.insert(null, 1, {
name: 'Plants'
});
// Insert an item into the 'People' node, after 'David'
tree.insert(
'People',
1,
{ name: 'Judy' }
);
// Insert an item before another item
tree.insertAfter('Kangaroo', {name: 'Horse'});
// Insert multiple items before another item
tree.insertAfter('Kangaroo', {name: 'Horse'}, {name: 'Giraffe'});
// Insert an item before another item
tree.insertAfter('Kangaroo', { name: 'Horse' });
// Insert multiple items before another item
tree.insertAfter('Kangaroo', { name: 'Horse' }, {
name: 'Giraffe'
});
// Insert an item before another item
tree.insertAfter(
'Kangaroo',
{ name: 'Horse' }
);
// Insert multiple items before another item
tree.insertAfter(
'Kangaroo',
{ name: 'Horse' },
{ name: 'Giraffe' }
);
// Insert an item after another item
tree.insertAfter('Kangaroo', {name: 'Horse'});
// Insert multiple items after another item
tree.insertAfter('Kangaroo', {name: 'Horse'}, {name: 'Giraffe'});
// Insert an item after another item
tree.insertAfter('Kangaroo', { name: 'Horse' });
// Insert multiple items after another item
tree.insertAfter('Kangaroo', { name: 'Horse' }, {
name: 'Giraffe'
});
// Insert an item after another item
tree.insertAfter(
'Kangaroo',
{ name: 'Horse' }
);
// Insert multiple items after another item
tree.insertAfter(
'Kangaroo',
{ name: 'Horse' },
{ name: 'Giraffe' }
);
// Append an item to the root
tree.append(null, {name: 'Plants'});
// Append an item to the 'People' node
tree.append('People', {name: 'Plants'});
// Append an item to the root
tree.append(null, {name: 'Plants'});
// Append an item to the 'People' node
tree.append('People', {name: 'Plants'});
// Append an item to the root
tree.append(null, {
name: 'Plants'
});
// Append an item to the 'People' node
tree.append('People', {
name: 'Plants'
});
// Prepend an item to the root
tree.prepend(null, {name: 'Plants'});
// Prepend an item at the start of the 'People' node
tree.prepend('People', {name: 'Plants'});
// Prepend an item to the root
tree.prepend(null, {name: 'Plants'});
// Prepend an item at the start of the 'People' node
tree.prepend('People', {name: 'Plants'});
// Prepend an item to the root
tree.prepend(null, {
name: 'Plants'
});
// Prepend an item at the start of the 'People' node
tree.prepend('People', {
name: 'Plants'
});
Removing items#
// Remove an item
list.remove('Kangaroo');
// Remove multiple items
list.remove('Kangaroo', 'Snake');
// Remove an item
list.remove('Kangaroo');
// Remove multiple items
list.remove('Kangaroo', 'Snake');
// Remove an item
list.remove('Kangaroo');
// Remove multiple items
list.remove(
'Kangaroo',
'Snake'
);
// Remove all selected items
list.removeSelectedItems();
// Remove all selected items
list.removeSelectedItems();
// Remove all selected items
list
.removeSelectedItems();
Moving items#
// Move an item within the same parent
tree.move('Sam', 'People', 0);
// Move an item to a different parent
tree.move('Sam', 'Animals', 1);
// Move an item to the root
tree.move('Sam', null, 1);
// Move an item within the same parent
tree.move('Sam', 'People', 0);
// Move an item to a different parent
tree.move('Sam', 'Animals', 1);
// Move an item to the root
tree.move('Sam', null, 1);
// Move an item within the same parent
tree.move(
'Sam',
'People',
0
);
// Move an item to a different parent
tree.move(
'Sam',
'Animals',
1
);
// Move an item to the root
tree.move(
'Sam',
null,
1
);
Updating items#
tree.update('Sam', {name: 'Samantha'});
tree.update('Sam', {name: 'Samantha'});
tree.update('Sam', {
name: 'Samantha'
});