react-vtree

3.0.0 verified Mon Apr 27 auth: no javascript

A lightweight React component for efficiently rendering large tree structures (millions of nodes) built on top of react-window. Current stable version is v3.0.0 (released 2023), which requires React 18+. Release cadence is irregular; v3.0.0 consolidated changes from a long beta, with v4.0.0 planned. Key differentiators: uses a generator-based treeWalker for flexible tree building, supports both fixed-size and variable-size items, and ships TypeScript definitions. Alternatives like react-virtualized-tree are heavier or less maintained.

Common errors

error TypeError: treeWalker is not a function or its return value is not iterable ↓

cause treeWalker is not a generator function or does not return an iterator.

fix

Ensure treeWalker is defined as a generator function: function* treeWalker() { ... }

error Error: The treeWalker function must yield objects with an `isOpenByDefault` field of type boolean. ↓

cause Missing or invalid `isOpenByDefault` field in yielded data.

fix

Add isOpenByDefault: true (or false) to all yielded data objects.

error Uncaught Error: No treeWalker provided to Tree component ↓

cause Missing treeWalker prop on Tree component.

fix

Pass a valid treeWalker function as the treeWalker prop to the Tree component.

error Warning: React does not recognize the `setOpen` prop on a DOM element. ↓

cause Spreading props from Node component to a DOM element when setOpen should not be passed.

fix

Destructure setOpen and do not pass it to the DOM element (e.g., inline style only passes style and other needed props).

Warnings

breaking v3.0.0 changed the shape of treeWalker function. Previous treeWalker used synchronous iteration; new treeWalker uses generator with yield for both initial nodes and children. ↓

fix Rewrite treeWalker as a generator function. See documentation for the new pattern.

deprecated v2.0.0 introduced recomputeTree with opennessState parameter; earlier manual node toggle methods are deprecated. ↓

fix Use recomputeTree with opennessState object instead of direct state mutations.

gotcha The treeWalker function must yield objects with an `isOpenByDefault` field (boolean). If omitted, the node will be treated as closed initially. ↓

fix Ensure `isOpenByDefault` is present in the yielded data.

gotcha When using TypeScript, the Node component's style prop is of type React.CSSProperties, but the library may pass a plain object. Ensure type compatibility. ↓

fix Use `style as React.CSSProperties` if needed.

breaking v2.0.0 removed the `toggle` prop from Node. You must use `setOpen` function passed via render props. ↓

fix Replace `toggle` with `setOpen` and call `setOpen(!isOpen)` to toggle.

gotcha The library does not support React 17; peer dependencies require React >=18. Installing on React 17 causes runtime errors. ↓

fix Upgrade to React 18+ or use react-vtree v2.x (requires React 16.8+).

Install

npm install react-vtree

yarn add react-vtree

pnpm add react-vtree

Imports

FixedSizeTree
```
import { FixedSizeTree } from 'react-vtree'
```
Common named import for fixed-size tree.
VariableSizeTree
```
import { VariableSizeTree } from 'react-vtree'
```
Common named import for variable-size tree.
default (Tree)
wrong
```
import { Tree } from 'react-vtree'
```
correct
```
import Tree from 'react-vtree'
```
Default export is the FixedSizeTree component; named Tree does not exist.

Quickstart

A complete minimal example: defining a tree structure, implementing the treeWalker generator, creating a Node component, and rendering a FixedSizeTree.

import { FixedSizeTree as Tree } from 'react-vtree'

const treeNodes = [{ id: 'root', name: 'Root', children: [{ id: 'c1', name: 'Child', children: [] }] }]

function* treeWalker() {
  for (const node of treeNodes) {
    yield { data: { id: node.id, isLeaf: node.children.length === 0, isOpenByDefault: true, name: node.name, nestingLevel: 0 }, nestingLevel: 0, node }
  }
  while (true) {
    const parent = yield
    for (const child of parent.node.children) {
      yield { data: { id: child.id, isLeaf: child.children.length === 0, isOpenByDefault: true, name: child.name, nestingLevel: parent.nestingLevel + 1 }, nestingLevel: parent.nestingLevel + 1, node: child }
    }
  }
}

const Node = ({ data: { name, isLeaf }, isOpen, style, setOpen }) => (
  <div style={style}>
    {!isLeaf && <button onClick={() => setOpen(!isOpen)}>{isOpen ? '-' : '+'}</button>}
    <span>{name}</span>
  </div>
)

createRoot(document.querySelector('#root')).render(<Tree treeWalker={treeWalker} itemSize={30} height={150} width={300}>{Node}</Tree>)