Documentation
Guides

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

optionwhen
rowSize: 28every 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").

Large tree
Gallery

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.