Virtualization

Using TanStack Virtual.

UsageCopy Anchor Link

import { VirtualList } from "@gpuixui/data";

<VirtualList height={320} aria-label="Files">
  {rows.map((row) => (
    <div key={row.id} style={{ height: 32 }}>
      <text>{row.label}</text>
    </div>
  ))}
</VirtualList>;

APICopy Anchor Link

VirtualListCopy Anchor Link

VirtualTableCopy Anchor Link

VirtualTableBodyCopy Anchor Link

The height a window needsCopy Anchor Link

A windowed surface computes its range from a viewport height and has no natural height of its own: a content-sized box would report a height, mount more rows and grow again. Give it a definite height when you can.

A height the layout cannot paint — NaN, an infinity, a negative, the value a computed pane measure has before the first layout — reads as no height, so the surface takes the share of its pane that the layout hands out and windows against the height that box painted:

<div style={{ display: "flex", flexDirection: "column", height: 320 }}>
  <VirtualTree aria-label="Files" rows={tree.rows} labelOf={labelOf} />
</div>

• VirtualTable fills its container and windows against the measured viewport frame, exactly as it does with a height;
• VirtualTree measures the column it fills and draws the list at that height. The runtime's <virtual-list> paints no surface of its own, so it reports no onLayout (measured on 0.11.0) — the list cannot measure itself.

The pane must bound the column's height. A surface with no viewport at all — an auto-height or non-flex parent — has nothing to fill and paints no rows, which is the same state as a window with no bound.

In a 320px pane both paint the window they paint at height={320}: 8 table rows and 10 tree rows in behaviour/paintable-height.test.tsx.

Paging versus windowingCopy Anchor Link

The two bound paint differently, and a grid usually wants one of them:

• a window mounts the rows near the viewport and follows the scroll — the reader can reach any row, and the set is never sliced;
• a page slices the filtered and sorted set at a page size and paints one slice — the reader moves the slice, and every row on it is mounted.

Paging is useTable's, and it runs on the same @tanstack/table-core pagination row model the sort and the filter do, so the page is a slice of what the core kept instead of a second filter:

Four rules are measured, not assumed:

• a filter, a search or a new sort returns to the first page — the records the reader was reading are not where the index says they are once the set changes (setQuery, pressSort, toggleSort and setSort all reset it); a new predicate tree does the same, and it arrives as a controlled prop rather than a gesture, so the index is stamped with the tree it was measured against and a replacement paints page one in the same commit;
• a page index past the set clamps to its last page — a saved workspace reopens with the page it was on, and a set that has since narrowed paints its last page instead of a blank one past the end — and the arrows and a page size change measure from the page it paints, so a saved index past the set cannot strand Previous on the page already shown or carry a new size past the reader's top row;
• a page size change keeps the reader's top row in view, so doubling the size shows the same records from the same first row;
• the selection is the kept set's, not the page's — a record chosen on page one is still chosen (and still saved) while page two paints, while the header's box covers only what it paints.

The page is part of the record a grid saves: save() writes pagination, and readGridState(stored) reads it back, so a workspace reopens on the page the reader left. pageSize of every row is Infinity, which JSON writes as null and the reader takes as every row again. A store-driven grid builds the core itself and passes onPaginationChange; ALL_ROWS, DEFAULT_PAGINATION, pageIndexOf, pageSizeOf, pageCountOf, clampPageIndex, withPageSize and readPagination are exported for the arithmetic it needs.

const table = useTable({ rows, keyOf: (row) => row.id, columns, pageSize: 20 });

<Button
  disabled={table.pageIndex >= table.pageCount - 1}
  onActivate={table.nextPage}
>
  Next
</Button>;
// `Page ${table.pageIndex + 1} of ${table.pageCount}` · `${table.rows.length} rows`

pagination/logic.test.ts holds the arithmetic, behaviour/table-pagination the page the shipped controller paints, and behaviour/pagination-example the screen in examples/table-pagination.example.tsx. A grid that must never slice its set uses the windowed surfaces above instead.

Edit this page on GitHubpackages/data/docs/virtualization.mdx