Rich Tree View - Lazy loading

Lazy load the data from your Tree View.

Basic usage

To dynamically load data from the server, including lazy-loading of children, you must create a data source and pass the dataSource prop to RichTreeView.

The data source also requires the getChildrenCount() attribute to handle tree data. getChildrenCount() returns the number of children for the item. If the children count is not available, but there are children present, it returns -1.

The items prop serves as the initial state.

If you want to dynamically load all items of RichTreeView, you can pass an empty array to the items prop, and the getTreeItems() method will be called on the first render.

Using react-query

The following demo uses fetchQuery from react-query to load data.

Loading indicators

While getTreeItems() fetches the root items, the tree displays the same loading rows as the loading prop. Use the itemsCount value in slotProps.loading to control the number of rows.

While an item fetches its children, the loading UI depends on the DOM structure:

• With domStructure="nested" and disableVirtualization, the item opens and displays loading rows in place of its children. The number of rows matches getChildrenCount() when the count is known.
• With the default flat structure, a circular progress indicator replaces the expansion icon.

You can customize the loading rows with the same slots and classes as the loading prop.

Customized loading UI

The demo below combines the customization options and adds transitions:

• The loading slot replaces the loading rows. It renders while the root items load and while an item fetches its children. Each custom row is wrapped in the TreeItemLoader component, which keeps the role, aria attributes, indentation, and height of a tree item.
• The loadingIcon slot of TreeItem replaces the circular progress indicator of an item whose children load.
• The groupTransition slot of TreeItem animates the expansion with a spring.
• The loading rows and the items share a staggered entrance animation. This makes the transition from the loading state to the loaded items read as one continuous motion.

Data caching

Custom cache

To provide a custom cache, use the dataSourceCache prop, which may be created from scratch or based on a third-party cache library. This prop accepts a generic interface of type DataSourceCache.

The following demo uses QueryClient from react-query as a data source cache.

Customize the cache lifetime

The DataSourceCacheDefault has a default time to live (ttl) of 5 minutes. To customize it, pass the ttl option in milliseconds to the DataSourceCacheDefault constructor, and then pass it as the dataSourceCache prop.

Auto-expand lazy-loaded items

Use the onItemsLazyLoaded callback to auto-expand items when their children are loaded. This callback is called both when new items are fetched from the server and when items are loaded from the cache.

In the example below, the server returns some items with their sub-items already included in the response. The onItemsLazyLoaded callback expands any returned item that has inline children. Because those children are pre-cached by the tree view, expanding them requires no additional network request.

Error management

When the fetch of an item's children fails, the item closes again and displays an error indicator in its icon container.

Lazy loading and label editing

To store the updated item labels on your server, use the onItemLabelChange() callback function.

Changes to the label are not automatically updated in the dataSourceCache and must be updated manually. The demo below shows you how to update the cache once a label is changed so the changes are reflected in the tree.

Lazy loading and adding items

Items added with the addItems() API method are only stored in the internal state of the component and are not added to the dataSourceCache. Collapsing and expanding their parent again replaces them with the response of the server.

The demo below shows you how to update the cache once an item is added so the changes are reflected in the tree. The children of the selected item are loaded before the new item is added, because the fetch triggered when expanding an item overrides the items added to it.

Imperative API

To use the apiRef object, you need to initialize it using the useRichTreeViewProApiRef() hook as follows:

const apiRef = useRichTreeViewProApiRef();

return <RichTreeViewPro apiRef={apiRef} items={ITEMS} />;

When your component first renders, apiRef.current is undefined. After the initial render, apiRef holds methods to interact imperatively with RichTreeView.

Update the children of an item

Use the updateItemChildren() API method to fetch the children of an item:

apiRef.current.updateItemChildren(
  // The id of the item to update the children of
  // null if the entire tree needs to be reloaded
  itemId,
);

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <RichTreeViewPro />
• <TreeItem />
• <TreeItemLoader />