Virtualization

Large trees can have a significant impact on render and usage performance, and cause slow interactions. Virtualization is a concept, where the performance hit of a very large list of items is mitigated by only rendering the items that are currently visible in the viewport.

While this is not trivial to do with nested structures like trees, Headless Tree makes this easy by flattening the tree structure and providing the tree items as flat list. Virtualization is not a included feature of Headless Tree, but you can easily pass this flat list to any virtualization library of your choice, and use that to create a tree that only renders the visible items.

In the sample below, react-virtual is used to virtualize the tree and render 100k items while still being performant in rendering and interaction.

warning

You likely will want to use proxified item instances instead of static item instances when using trees with many items. Read this guide to learn more about Proxy Item Instances. You can use them by setting the instanceBuilder tree config option to buildProxiedInstance, a symbol that you can import from @headless-tree/core.

If you need to need a ref to the virtualized DOM items, keep in mind that treeItem.getProps() also returns a ref that needs to be assigned to the DOM element. Also keep in mind that the ref function of a DOM element is called both on mount and unmount, and calling treeItem.getProps() will fail if the item is already unloaded in the tree. Calling treeItem.getProps() outside the ref, like the following, will work:

const props = item.getProps();
return (
  <button
    {...props}
    key={virtualItem.key}
    data-index={virtualItem.index}
    ref={(r) => {
      virtualizer.measureElement(r);
      props.ref(r);
    }}
  />
);