react-vtree

react-vtree is a React library for efficiently rendering large, hierarchical tree structures - file explorers, nested comment threads, org charts, or any recursive dataset - without paying the DOM cost of rendering every node up front. It layers a generator-based tree-walking API on top of react-window’s windowing engine, so only the currently visible rows are mounted while the rest of the tree stays virtual.

The library ships two tree variants, FixedSizeTree for uniform row heights and VariableSizeTree for per-node dynamic sizing, both driven by a user-supplied treeWalker generator that yields node data lazily. Support for asynchronous data loading, idle-callback-based background tree building for very large datasets, and multiple root nodes make it suited for real-world file-system-style UIs where nodes can expand, load children on demand, or number in the tens of thousands.

What You Get

• FixedSizeTree component for trees with uniform row heights, virtualized via react-window’s FixedSizeList
• VariableSizeTree component for trees with per-node dynamic heights, with a resize() API to recalculate list offsets
• A generator-based treeWalker contract for describing arbitrary tree shapes, including multiple root nodes, without conforming to a fixed data schema
• Built-in support for asynchronous/lazy-loaded child data via the async prop, preserving open/closed state across rebuilds
• requestIdleCallback-based background tree building (placeholder + buildingTaskTimeout) to avoid UI freezes on very large trees

Common Use Cases

• File and folder browsers - rendering deeply nested filesystem-like trees where folders load their children on expand
• Nested comment threads - virtualizing large discussion trees so only visible replies are rendered
• Org charts and hierarchical dashboards - displaying large reporting-structure or category trees without scroll jank
• IDE-style project/outline panels - collapsible tree navigation over thousands of files or symbols

Under The Hood

Architecture The library is a thin, focused wrapper around react-window that adds a tree-walking layer on top of virtualization primitives. Execution starts in the generic Tree component (src/Tree.tsx), a PureComponent whose state holds a flattened order array (visible node ids) and a records map (linked NodeRecord entries with parent/child/sibling pointers) built by a user-supplied treeWalker generator. FixedSizeTree and VariableSizeTree subclass Tree, injecting a createTreeComputer-produced computeTree function via createRecord factories that differ only in the shape of the per-node public state. getDerivedStateFromProps triggers a full tree rebuild whenever the treeWalker identity changes or no order exists yet, and delegates partial diffs (opening or closing a subtree) to a splice-based order-array patch, avoiding a full tree walk on every toggle. The generic base renders nothing itself - it hands order, records, and an itemKey/itemData bundle down to the underlying react-window list component, which performs the actual DOM virtualization. Because both concrete tree types and the row-indexing helper read directly from the shared NodeRecord linked-list structure, that abstraction is the one piece the rest of the library depends on.

Tech Stack The package declares a single runtime dependency, react-merge-refs, with react and react-window as peer dependencies, keeping the published bundle minimal. The codebase is fully TypeScript with strict settings, built via an esbuild-based bundler into an ESM-only distribution with generated type declarations, and typechecked with an experimental native TypeScript preview toolchain. Linting combines two linters under one script, formatting is automated, and releases are cut via semantic-release with changelog automation. A Storybook instance hosts interactive stories used both for manual QA and a published demo site. There is no server or database component - this is a pure client-side React library.

Code Quality The test suite covers both tree variants plus a dedicated multi-root scenario, backed by a shared test-utilities module that provides mocked list components, idle-callback controllers, and state-introspection helpers rather than ad hoc mocking per test file. Tests mock the underlying windowing library wholesale and assert on internal tree state and on the props passed to the list component, including coverage of imperative scroll APIs. Core logic is intricate array-splicing designed to stay within JavaScript engine argument-count limits, and it is documented with unusually thorough inline comments explaining non-obvious invariants. Typing is strict and pervasive, with generics constraining node-data and state shapes throughout. Continuous integration runs linting, type checking, tests, and the build concurrently on every push and pull request.

API Design The public surface is deliberately small - two exported tree components plus a generator-based treeWalker contract that lets consumers describe arbitrary tree shapes without adapting to a fixed node-shape convention. This coroutine-style design is unusual for a UI library’s props API - it trades a modest learning curve for flexibility, supporting async data loading, background building, and multiple roots - and is documented through runnable example stories covering each of those harder scenarios. TypeScript generics propagate the consumer’s node-data type end-to-end, so node-rendering components receive fully typed props without casts. The main friction point is that consumers must remember to memoize the treeWalker themselves, and the interaction between the async, placeholder, and idle-callback options has several modes that require reading prose rather than being self-evident from the types alone.