useTreeData

Manages state for an immutable tree data structure, and provides convenience methods to update the data over time.

install	`yarn add @react-stately/data`
version	3.4.7
usage	`import {useTreeData} from '@react-stately/data'`

View repository

GitHub

View package

NPM

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`	`T[]`	Initial root items in the tree.
`initialSelectedKeys`	`Iterable<Key>`	The keys for the initially selected items.
`getKey`	`( (item: T )) => Key`	A function that returns a unique key for an item object.
`getChildren`	`( (item: T )) => T[]`	A function that returns the children for an item object.

Interface#

Properties

Name	Type	Description
`items`	`TreeNode<T>[]`	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<T>`	Gets a node from the tree by key.
`insert( parentKey: Key \| \| null, index: number, ...values: T[] ): void`	Inserts an item into a parent node as a child.
`insertBefore( (key: Key, , ...values: T[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: T[] )): void`	Inserts items into the list after the item at the given key.
`append( (parentKey: Key \| \| null, , ...values: T[] )): void`	Appends an item into a parent node as a child.
`prepend( (parentKey: Key \| \| null, , ...value: T[] )): 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, index: number ): void`	Moves an item within the tree.
`update( (key: Key, , newValue: T )): 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.

let tree = useTreeData({
  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
  items={tree.items}
  selectedKeys={tree.selectedKeys}
  onSelectionChange={tree.setSelectedKeys}>
  {node =>
    <Section title={node.value.name} items={node.children}>
      {node => <Item>{node.value.name}</Item>}
    </Section>
  }
</ListBox>

let tree = useTreeData({
  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
  items={tree.items}
  selectedKeys={tree.selectedKeys}
  onSelectionChange={tree.setSelectedKeys}>
  {node =>
    <Section title={node.value.name} items={node.children}>
      {node => <Item>{node.value.name}</Item>}
    </Section>
  }
</ListBox>

let tree = useTreeData({
  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
  items={tree.items}
  selectedKeys={tree
    .selectedKeys}
  onSelectionChange={tree
    .setSelectedKeys}
>
  {(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 within the same parent
tree.move('Sam', 'People', 0);

// Move an item to a different parent
tree.move('Sam', 'Animals', 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
);

Updating items#

tree.update('Sam', {name: 'Samantha'});

tree.update('Sam', {name: 'Samantha'});

tree.update('Sam', {
  name: 'Samantha'
});