Skip to content

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
10-000-items.svelte
<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
variable-row-heights.svelte
<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

NameTypeDefaultDescription
countrequirednumber—Total logical rows. Use an options object with a get count() getter if the backing array length changes - reads rerun whenever scroll geometry updates.
itemHeightrequirednumber | ((index: number) => number)—Fixed height or per-item height function.
overscannumber | undefined—Extra items rendered above and below the viewport.

Returns

From phoundry-ui@0.4.21

NameTypeDefaultDescription
itemsVirtualItem[]—Visible items with index, start position, and size.
totalHeightnumber—Total scrollable height in pixels.
scrollOffsetnumber—Current scroll offset.
containerHeightnumber—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.action on the scroll container.
  • For variable-height items, pass a function to itemHeight - e.g. (i) => i % 5 === 0 ? 48 : 32.
  • Increase overscan if you see flickering during fast scrolling.
  • Use scrollToIndex for keyboard navigation or “scroll to top/bottom” buttons.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.