VirtualList
Headless virtual scrolling utility. Renders only visible items for lists with thousands of rows.
import { createVirtualList } from "phoundry-ui";10,000 Items
Loading interactive example…
View source
<script lang="ts"> import { createVirtualList } from "phoundry-ui";
const vl = createVirtualList({ count: 10000, itemHeight: 32, overscan: 5 });</script>
<div use:vl.action class="h-64 overflow-auto rounded-lg border border-border-muted" onscroll={vl.handleScroll}> <div style="height: {vl.totalHeight}px; position: relative;"> {#each vl.items as item (item.index)} <div style="position: absolute; top: {item.start}px; height: {item.size}px; width: 100%;" class="flex items-center border-b border-border-muted px-3 text-sm" > Row {item.index} </div> {/each} </div></div><p class="mt-2 text-xs text-txt-tertiary"> Rendering {vl.items.length} of 10,000 items</p>Variable row heights
Loading interactive example…
View source
<script lang="ts"> import { Button } from "phoundry-ui"; import { createVirtualList } from "phoundry-ui";
const vlVariable = createVirtualList({ count: 800, itemHeight: (i: number) => (i % 9 === 0 ? 52 : 30), overscan: 8, });</script>
<p class="mb-2 text-xs text-txt-secondary"> Every 9th row is taller- <code>itemHeight</code> as a function recomputes offsets cumulatively.</p><div class="mb-2 flex gap-2"> <Button size="sm" onclick={() => vlVariable.scrollToIndex(400, "center")} >Jump to index 400</Button ></div><div use:vlVariable.action class="h-56 overflow-auto rounded-lg border border-border-muted" onscroll={vlVariable.handleScroll}> <div style="height: {vlVariable.totalHeight}px; position: relative;"> {#each vlVariable.items as item (item.index)} <div style="position: absolute; top: {item.start}px; height: {item.size}px; width: 100%;" class="flex items-center border-b border-border-muted px-3 text-xs" class:bg-surface-sunken={item.index % 9 === 0} > {item.index % 9 === 0 ? "Section header" : "Row"} {item.index} </div> {/each} </div></div>Options
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
countrequired | number | — | Total logical rows. Use an options object with a get count() getter if the backing array length changes - reads rerun whenever scroll geometry updates. |
itemHeightrequired | number | ((index: number) => number) | — | Fixed height or per-item height function. |
overscan | number | undefined | — | Extra items rendered above and below the viewport. |
Returns
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
items | VirtualItem[] | — | Visible items with index, start position, and size. |
totalHeight | number | — | Total scrollable height in pixels. |
scrollOffset | number | — | Current scroll offset. |
containerHeight | number | — | Measured container height. |
handleScroll | (e: Event) => void | — | Scroll event handler to attach to the container. |
scrollToIndex | (index: number, align?: "start" | "center" | "end" | "auto") => void | — | Scroll so the given index is visible; defaults to smart (“auto”) scrolling. |
action | (el: HTMLElement) => { destroy: () => void; } | — | Svelte use:action for the scroll container. |
Usage tips
- This is a headless utility - you provide the container and item markup. Use
use:vl.actionon the scroll container. - For variable-height items, pass a function to
itemHeight- e.g.(i) => i % 5 === 0 ? 48 : 32. - Increase
overscanif you see flickering during fast scrolling. - Use
scrollToIndexfor keyboard navigation or “scroll to top/bottom” buttons.