Virtual Tree

ProNew

A tree for tens of thousands of rows that renders only the rows in view while keeping exact aria-level, position and set size.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it when a tree can show thousands of rows at once: device lists, repositories, log folders, large taxonomies.

Do not use it for small trees; the fixed row height and absolute positioning add constraints you do not need.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/virtual-tree

It uses tree-view, which the CLI installs for you.

It needs @tanstack/react-virtual.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The tree.
`rowHeight`	`number`	`32`	Row height in px. All rows share it.
`overscan`	`number`	`8`	Extra rows drawn above and below.
`initialRect`	`{ width, height }`	-	Size before measuring (server rendering, tests).
`revealId`	`string \| null`	-	Scrolls this row into view and focuses it when it changes. Open its parents first.
`...`	-	-	All `useTree` options.

Accessibility

Every rendered row has aria-level, aria-posinset and aria-setsize from the full tree, so assistive technology reports "7 of 20,240" even though only about 30 rows are in the page.
The focused row stays in the document when scrolled out of view, so the tab stop never disappears.
Rows have a fixed height; give the tree a height (className="h-96").

Keyboard

All the tree keys from tree-view.
Home / End and PageUp / PageDown scroll the target row into view before focusing it.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (virtual-tree.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it when a tree can show thousands of rows at once: device lists, repositories, log folders, large taxonomies.

Do not use it for small trees; the fixed row height and absolute positioning add constraints you do not need.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/virtual-tree

It uses tree-view, which the CLI installs for you.

It needs @tanstack/react-virtual.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The tree.
`rowHeight`	`number`	`32`	Row height in px. All rows share it.
`overscan`	`number`	`8`	Extra rows drawn above and below.
`initialRect`	`{ width, height }`	-	Size before measuring (server rendering, tests).
`revealId`	`string \| null`	-	Scrolls this row into view and focuses it when it changes. Open its parents first.
`...`	-	-	All `useTree` options.

Accessibility

Every rendered row has aria-level, aria-posinset and aria-setsize from the full tree, so assistive technology reports "7 of 20,240" even though only about 30 rows are in the page.
The focused row stays in the document when scrolled out of view, so the tab stop never disappears.
Rows have a fixed height; give the tree a height (className="h-96").

Keyboard

All the tree keys from tree-view.
Home / End and PageUp / PageDown scroll the target row into view before focusing it.

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

Testing

The component ships with a Testing Library test (virtual-tree.test.tsx) that covers its keyboard paths, roles and states.