VirtualList

Windowing primitive for long lists. VirtualList owns a native scroll container and renders only the visible rows plus overscan; you own the row markup through the row snippet. It scrolls vertically by default and horizontally under horizontal.

Use VirtualList to window an already-loaded large collection. Use LoadMore to fetch another page as the reader reaches the end of a growing result set; the two can be composed when a paginated collection also needs windowed rendering — or use onEndReached below to drive the fetch from scroll position directly.

For two-dimensional data, reach for DataGrid rather than composing grids out of this: it owns column virtualization and role="grid" semantics. The repository's virtualization guide explains why cinder ships three windowing engines and which one backs each component.

Choosing a row-sizing mode

By default every row is exactly itemHeight pixels tall. That is the fast path: offsets are pure arithmetic and no row is ever measured. (The component always observes its own scroll container to track viewport size, in both modes — what dynamicSize adds is per-row measurement.)

When rows genuinely vary — they wrap, embed media, or hold user content — set dynamicSize. itemHeight then becomes the initial estimate for rows that have not been measured yet. Each row is measured once as it mounts, its real size is cached by key, and when a measurement differs from the estimate the scroll offset is corrected before paint so the viewport does not visibly jump.

Prefer the fixed path when it is honest. dynamicSize costs a ResizeObserver subscription per mounted row and a rebuilt offsets table each time a measurement lands, and it buys nothing for a list whose rows really are uniform.

Pass getKey whenever dynamicSize is on. Measured sizes are cached by key, so index-derived keys will attribute a cached size to the wrong row the first time items reorder.

Scrolling along the inline axis

Set horizontal to window a row of items instead of a column. The component then owns a horizontally-scrolling container, positions rows along the inline axis, and reads its scroll offset from scrollLeft rather than scrollTop.

Two props are reinterpreted rather than renamed. itemHeight becomes each item's width, and height becomes the container's inline-size. So does the --cinder-virtual-list-height custom property, which keeps its name and switches to driving inline-size. This is deliberate: renaming them would mean either a second parallel set of props that is meaningless in the other mode, or a breaking rename for every existing vertical caller. The names stay; read them as "extent along the main axis" and "extent of the viewport."

<VirtualList items={columns} itemHeight={160} horizontal height="480px" aria-label="Columns">
  {#snippet row(column)}
    <div style="inline-size: 160px;">{column.label}</div>
  {/snippet}
</VirtualList>

Right-to-left

Right-to-left is handled, not assumed. The writing direction is resolved from the container's computed style at mount, so a dir="rtl" anywhere up the tree is enough — you do not pass anything extra.

Underneath, this is messier than it looks. In a right-to-left container browsers have historically disagreed about what scrollLeft even means: whether it starts at zero or at the maximum, and whether it grows positive or negative as you scroll away from the start edge. Rather than assume one, the component measures which convention the browser implements — once per document, with a detached probe — and normalizes every read and write into a single start-edge-relative offset. Row positions use logical CSS properties throughout, so nothing depends on physical left and right.

The practical consequence for you: scrollToIndex, stickToBottom, and the row context.start offset all mean the same thing in both directions. "The start" is the left edge in a left-to-right list and the right edge in a right-to-left one.

Usage

<script lang="ts">
  import { VirtualList } from '@lostgradient/cinder/virtual-list';

  const events = Array.from({ length: 10_000 }, (_, index) => ({
    id: `event-${index}`,
    label: `Event ${index}`,
  }));
</script>

<VirtualList
  items={events}
  itemHeight={32}
  height="20rem"
  getKey={(event) => event.id}
  aria-label="Events"
>
  {#snippet row(event, context)}
    <div data-index={context.index}>{event.label}</div>
  {/snippet}
</VirtualList>

Use stickToBottom for live log tails: appending while the user is already at the bottom keeps the newest row in view, while appending with the viewport scrolled up leaves the scroll position unchanged.

Scrolling to an item

bind:ref hands back a typed handle with scrollToIndex:

<script lang="ts">
  import { VirtualList, type VirtualListRef } from '@lostgradient/cinder/virtual-list';

  let list = $state<VirtualListRef | undefined>();
</script>

<button type="button" onclick={() => list?.scrollToIndex(500, { align: 'start' })}>
  Jump to event 500
</button>

<VirtualList bind:ref={list} items={events} itemHeight={32} {row} aria-label="Events" />

align accepts 'start', 'center', 'end', or 'auto' (the default, which leaves the position alone when the row is already fully visible). Under dynamicSize the target accounts for every measured row before it, and re-settles if rows above it are measured for the first time mid-scroll.

Chat transcripts and infinite scroll

Set reverse for a chat-style list. It opens at the newest item and returns there whenever one arrives, however far back the reader has scrolled.

reverse names the anchoring, not the ordering. Items stay in their natural order — oldest at index 0, newest last — and the array is never flipped. This is worth being explicit about, because the name suggests otherwise.

It is deliberately distinct from stickToBottom, which pins only when the reader is already at the bottom. Choose by what should happen to someone reading history when a new message lands: stickToBottom leaves them alone, reverse brings them to the newest item. When both are set, reverse wins.

Prepending is handled as its own case. Loading a page of older history grows the list above the reader, and the component anchors to the row they were on so it stays put — it does not pin to the end, and it does not leave them silently looking at a different row.

Loading more in both directions

onEndReached fires when the reader comes within overscan items of the end; onStartReached does the same at the start. Together they give bi-directional infinite scroll.

<VirtualList
  items={rows}
  itemHeight={40}
  height="320px"
  onEndReached={loadNewer}
  onStartReached={loadOlder}
  getKey={(row) => row.id}
  aria-label="Feed"
>
  {#snippet row(item)}
    <div>{item.label}</div>
  {/snippet}
</VirtualList>

Each callback fires once per approach, not once per scroll event, and re-arms when the item count changes. That pairing is what makes the obvious usage safe: appending in response lets the next approach fire, while a source that returns nothing leaves the count unchanged and the callback latched, so it does not spin.

Both callbacks are also evaluated when the item count changes, not only on scroll — an append can bring the end into range without the reader moving at all.

Remembering the scroll position

scrollRestoration writes the reader's position to sessionStorage and restores it when the list mounts again, so navigating away and back returns them to where they were.

It needs a scrollRestorationId, and there is deliberately no default. An implicit key — derived from position in the tree, or mount order — would quietly hand one list's remembered offset to a different list after an unrelated refactor, and two lists on one page would overwrite each other. Pick something tied to what the list shows.

<VirtualList
  items={rows}
  itemHeight={40}
  height="480px"
  scrollRestoration
  scrollRestorationId="inbox"
  aria-label="Inbox"
>
  {#snippet row(item)}
    <div>{item.subject}</div>
  {/snippet}
</VirtualList>

Two details worth knowing. Under dynamicSize the position is restored by index rather than by pixel offset: at mount every row is still an estimate, so the saved offset points at a different row than it did when saved — scrolling to the index lands on the row the reader actually left, and the settle pass follows it as the rows above are measured. And a saved position whose row no longer exists is dropped rather than clamped, because clamping would drop the reader somewhere arbitrary and then save that as though it were their place.

Storage failures are swallowed throughout. A browser in private mode can throw on reading sessionStorage, not just writing to it, and losing a remembered offset must never break the list.

Sticky rows

stickyItems names the indexes that pin to the leading edge while the reader scrolls past them — section headers in a grouped list, most often.

The part that virtualization would otherwise break is keeping them mounted. A row whose index has left the rendered window is normally unmounted, so the heading would disappear at exactly the moment it is meant to be pinned. The component keeps the active sticky row in the DOM past its window, and re-sorts the rendered set by index so a keyed {#each} does not move it behind the rows that follow it.

Setting stickyItems also makes scrollToIndex header-aware. A pinned header covers the leading edge, so a row aligned flush to it lands underneath — in a list where the header and its rows share a height, completely underneath. Destinations are offset by the header that will cover them, which applies to the component's keyboard navigation and to scrollToIndex calls of your own.

Invalid entries — duplicates, non-integers, indexes outside the list — are dropped rather than throwing. A bad sticky index is a cosmetic problem, not a correctness one.

<VirtualList items={rows} itemHeight={36} height="360px" stickyItems={headerIndexes}>
  {#snippet row(item)}
    <div>{item.label}</div>
  {/snippet}
</VirtualList>

Announcing position to assistive technology

Every row carries aria-posinset and aria-setsize. Both describe the full collection, not the rendered window — without them a screen reader announces what is mounted, so a 10,000-row list reads as "3 of 12". aria-posinset is 1-based, as the specification requires, while the row's context.index stays 0-based.

Scrolling behaviour

smoothScroll makes scrollToIndex animate by default. An explicit behavior in the call still wins, so a single jump-to remains available on a list that otherwise animates. Scroll corrections under dynamicSize are never animated whatever this is set to: a smooth correction would visibly perform the jump it exists to hide.

adaptiveOverscan grows overscan while the reader is scrolling fast and shrinks it back when they slow down. overscan becomes a floor rather than a fixed value, so turning this on can only ever render more rows than the configured value, never fewer. The growth is bounded — an unbounded overscan during a fling would mount thousands of rows and defeat virtualizing at all.