# Headless virtualization `` virtualizes rows and columns for you. When you render your own markup, you virtualize yourself with the same engine SvGrid uses - `createSvelteVirtualizer` (reactive) or `createVirtualizer` (framework-agnostic). Only the rows in view get DOM nodes, so 100k rows stay smooth. > Live demo: Headless virtualization - https://svgrid.com/demos/187-headless-virtual/ ## The idea A virtualizer answers two questions as the user scrolls: **which items are visible**, and **how far to offset them**. You give it the item `count`, an `estimateSize` (row height), and the `viewportHeight`; it gives you the virtual items to render plus the total size to reserve. You feed it the live scroll position with `setScrollOffset`, and read `version` so your derived values recompute. ```svelte ``` ## Render only what's visible Reserve the full scroll height with a spacer, then absolutely-position each visible row at its `start` offset: ```svelte
{#each items as vi (vi.key)} {@const row = rows[vi.index].original as Row}
{row.name} - {row.score}
{/each}
``` `getVirtualItems()` returns only the ~20 rows in view (plus `overscan`), each with `index`, `start` (px offset), `size`, and `key`. As the user scrolls, `setScrollOffset` bumps `version` and the list re-computes; the other 99,980 rows never touch the DOM. ## Columns too For very wide grids, `createColumnVirtualizer` does the same across leaf columns (horizontal). Drive it with `setScrollOffset(scrollLeft)` on the container's horizontal scroll: ```ts const colVirtualizer = createColumnVirtualizer({ count: leafColumns.length, viewportWidth: containerWidth, estimateSize: (i) => leafColumns[i].getSize(), overscan: 3, }) ``` ## Moving the window less often Two options shape how the window follows a scroll. `overscanBehind` keeps fewer items on the side the scroll is leaving, while the full `overscan` stays ahead of it. `overscanMin` keeps the window where it is while at least that many items are still rendered ahead of the scroll, and moves it only when the scroll runs past them, with the full `overscan` ahead again: ```ts const colVirtualizer = createColumnVirtualizer({ count: leafColumns.length, viewportWidth: containerWidth, estimateSize: (i) => leafColumns[i].getSize(), overscan: 5, // ahead of the scroll right after a move overscanBehind: 1, // behind it overscanMin: 2, // never fewer ahead; the window moves 4 items at a time }) ``` Moving a column window touches every rendered row, about the same work whether one column enters or four, so a few larger moves cost less than many one-column moves, and the scroll frames between moves change nothing. `` runs its column window this way. A window built at rest, or after a jump to items outside the rendered window, carries `overscanMin`. While the window holds, `version` does not change and `getState().scrollOffset` keeps the offset of the last move. Read the scroll position from your container if something else has to follow it every frame. ## Which one to use | Export | Use when | | --- | --- | | `createSvelteVirtualizer` | Inside a Svelte component - exposes a reactive `version` to re-derive from. | | `createVirtualizer` | Framework-agnostic - a non-Svelte custom layer / worker (subscribe manually). | | `createColumnVirtualizer` | Horizontal (column) virtualization. | `VirtualItem`, `VirtualizerOptions`, and `VirtualizerState` are exported for type annotations. ## It is already on Row virtualization is the default, which is why a large grid needs no configuration to stay responsive. The DOM holds the visible window, not the row count - open the inspector on the grid below and you will find a few dozen rows, not five thousand. ```svelte ``` ## Columns need their own opt-in Row virtualization still renders every column of every visible row, so a wide grid stays slow until you add `columnVirtualization`. The trade is real: off-screen columns are not in the DOM, so anything that walks the row's cells - a stylesheet selecting the nth child, a screenshot test - sees only the window. ```svelte ``` ## See also - [Build a table from scratch](https://svgrid.com/docs/help/headless/build-a-table/) - render non-virtualized first - [Row models](https://svgrid.com/docs/help/headless/row-models/) - [Benchmarks](https://svgrid.com/docs/help/benchmarks/) - the 1M-row numbers --- SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/headless/virtualization/ . All docs: https://svgrid.com/llms.txt