Virtualization
Render trees of hundreds of thousands of visible items - a window of the rows in view, with the keyboard, focus and drag and drop intact.
A tree renders every visible item by default. That is right for most trees, and it stops being right somewhere past a few thousand visible rows. Install the virtualization feature and the tree renders only the rows in view, plus a few on each side: a hundred thousand expanded items scroll, move the focus and drag like a dozen.
Virtualization is a feature (Features), and costs nothing without it:
virtualization(), VirtualItems and useTreeVirtualWindow come from its own entry
(@fragiola/tree-react/virtualization), the virtualizer lives in the core (no library, no
dependency), and a bundle that never imports the entry leaves all of it out.
Installing it
Install virtualization(options) in the model's features, render the rows with VirtualItems,
and give the root a height and a scroll:
import { createTreeModel, type ItemOf, Tree } from "@fragiola/tree-react";
import { VirtualItems, virtualization } from "@fragiola/tree-react/virtualization";
const features = [virtualization({ estimateRowSize: 28 })] as const;
export function Files() {
const [model] = useState(() => createTreeModel<Types, typeof features>(json, { features }));
return (
<Tree.Root model={model} aria-label="Files" className="files">
<VirtualItems<Types>>{(item) => <Row item={item} />}</VirtualItems>
</Tree.Root>
);
}
/** A row: no Tree.Group, a virtualized tree is flat. */
function Row({ item }: { item: ItemOf<Types> }) {
return (
<Tree.Item item={item}>
<Tree.ItemContent className="row">
<Tree.Toggle />
<span>{item.label}</span>
</Tree.ItemContent>
</Tree.Item>
);
}.files {
height: 480px;
overflow: auto;
}The root is the element that scrolls (or give virtualization() a scrollElement), and the rows
start at the top of its content box: put a header outside the root.
A flat tree
A virtualized tree renders its rows as siblings in the root: no Tree.Group holds them. Each
item still carries its aria-level, aria-posinset and aria-setsize, which is how the WAI-ARIA
tree pattern describes a flat tree, so a screen reader reads the same structure. The indentation
is the item's depth: --tree-depth is on every part of an item, as in a nested tree
(Styling the depth).
Between the rows, VirtualItems puts spacers (data-tree-part="spacer", aria-hidden)
that take the place of the rows it does not render, so the scrollbar is the whole tree's.
Row sizes
| option | when |
|---|---|
rowSize: 28 | every row is 28px, always: the fastest, nothing is measured. Your CSS must give the rows that height |
rowSize: (row) => … | each row's size is known from its VisibleItem (a level, a kind): exact, not measured |
estimateRowSize: 28 (or a function) | the rows are measured once rendered, through the root window's ResizeObserver; the estimate holds until then. Right for rows a theme or the content sizes |
A measured row keeps its size while it stays a visible item, scrolled away and back. When a row
above the view is measured, the engine keeps what is in view in place (and sets
overflow-anchor: none on the scroll element, so the browser does not move it a second time).
Measure the item's own element: give rows padding, not margins.
overscan (default 8) is how many rows are rendered past each edge of the view, and
initialViewportSize the view's size while the scroll element has none (a server render, a test
in jsdom, a hidden tree). With none, a virtualized tree renders no rows until it is on screen.
Keyboard, focus and scrolling
Every key works across the whole tree, not just the rows on screen. End, Home, the arrows, type-ahead and the keyboard drag move the focus to an item outside the window: the engine scrolls to it, it renders, and DOM focus lands on it. PageDown and PageUp move the focus by a view's worth of rows (only in a virtualized tree: elsewhere they scroll the page as usual).
The roving tab stop stays rendered wherever the scroll is, so Tab always finds the tree, and so
do the item being renamed and the row a pointer pressed. engine.run("scroll-to", { itemId, align }) scrolls to any visible item, rendered or not.
Drag and drop
A pointer drag auto-scrolls the virtualizer's scroll element near its edges, and the rows that come into view become drop targets; the dragged row keeps its pointer capture even when it scrolls out of view. A keyboard drag scrolls each target into view as the arrows move it. The drop indicator is placed by the rows' offsets, rendered or not.
Reading the window
engine.get("virtual-window") is what VirtualItems renders: the rows (each a
VirtualRow, with its offset, size and the spaceBefore to leave empty), the range in view
plus the overscan, the totalSize and the spaceAfter. Read it with useTreeVirtualWindow()
(Vue: the composable of the same name; Angular: injectTreeVirtualWindow()), from the same entry,
inside the root, to render the rows your own way; outside it, a tree ref typed by the features
(useTreeRef<Types, typeof features>()) reads engine.get("virtual-window").
The large tree holds 1 000 folders of 100 files, all expanded: 101 000 items, with a window of a few dozen in the DOM.
AI and automation
Drive the tree from an assistant or a script with the JSON commands a key or a click runs, validated, described by JSON Schemas and policed by middleware.
Right-to-left trees
A tree in Arabic, Hebrew or Persian needs no option - the engine reads the root's direction, and logical CSS properties mirror the rest.