@humanspeak/svelte-virtual-list

A high-performance virtual list component for Svelte 5 applications that efficiently renders large datasets with minimal memory usage.

Features

• 📏 Dynamic item height handling - no fixed height required
• 🔄 Automatic resize handling for dynamic content
• 📝 TypeScript support with full type safety
• 🚀 SSR compatible with hydration support
• ✨ Svelte 5 runes and snippets support
• 🎨 Customizable styling with class props
• 🐛 Debug mode for development
• 🎯 Smooth scrolling with configurable buffer zones
• 🧠 Memory-optimized for 10k+ items
• 🧪 Comprehensive test coverage (vitest and playwright)
• 🚀 Progressive initialization for large datasets
• 🕹️ Programmatic scrolling with scroll
• ♾️ Infinite scroll support with onLoadMore
• ♿ Keyboard-accessible viewport (focusable labeled region, standard scroll keys)

Requirements

• Svelte 5
• Node.js 18+

Installation

# Using pnpm (recommended)
pnpm add @humanspeak/svelte-virtual-list

# Using npm
npm install @humanspeak/svelte-virtual-list

# Using yarn
yarn add @humanspeak/svelte-virtual-list

Basic Usage

<script lang="ts">
    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'

    const items = Array.from({ length: 1000 }, (_, i) => ({
        id: i,
        text: `Item ${i}`
    }))
</script>

<SvelteVirtualList {items}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>

Props

| Prop | Type | Default | Description | | ---------------------------- | ----------------------------------- | ------------------- | ----------------------------------------------------------------------------- | | items | T[] | Required | Array of items to render | | itemKey | (item, index) => string \| number | - | Stable identity for measurement and responsive anchor preservation | | orientation | 'vertical' \| 'horizontal' | 'vertical' | Active layout axis; may change reactively (horizontal is LTR-only) | | defaultEstimatedItemSize | number | 40 | Axis-neutral initial size; takes precedence over the height alias | | defaultEstimatedItemHeight | number | 40 | Initial height estimate used until items are measured | | bufferSize | number | 20 | Number of items rendered outside the viewport | | debug | boolean | false | Enable debug logging and visualizations | | containerClass | string | '' | Class for outer container | | viewportClass | string | '' | Class for scrollable viewport | | viewportLabel | string | 'Scrollable list' | Accessible label for the focusable viewport region | | contentClass | string | '' | Class for content wrapper | | itemsClass | string | '' | Class for items container | | testId | string | '' | Base test id used in internal test hooks (useful for E2E/tests and debugging) | | onLoadMore | () => void \| Promise<void> | - | Callback when more data is needed for infinite scroll | | loadMoreThreshold | number | 20 | Items from end to trigger onLoadMore | | hasMore | boolean | true | Set to false when all data has been loaded | | onRangeChange | (range) => void | - | Fires when the rendered range or at-top/at-bottom state changes |

Measured header and footer

Optional header?: Snippet and footer?: Snippet take no arguments. They stay mounted outside the virtualized rows and scroll with content; they are not sticky. In horizontal mode they are leading and trailing content. Their wrappers isolate child margins and add no spacing; snippets provide their own visual dimensions.

<SvelteVirtualList {items}>
    {#snippet header()}<h2>Results</h2>{/snippet}
    {#snippet renderItem(item)}<article>{item.title}</article>{/snippet}
    {#snippet footer()}<p>End of results</p>{/snippet}
</SvelteVirtualList>

Content extent is measured header + estimated/measured rows + measured footer. Short lists stay at the start, with spare viewport space after the footer. Row counts, indices, averages and loading thresholds exclude snippets. Header/footer resize preserves the visible reading row, physical start stays at zero, and a pinned physical end stays pinned. Replacement, removal and orientation changes remeasure the content.

Index alignment includes the header offset. Aligning the last row to end leaves the footer below that row; scrollToOffset addresses the entire content from zero, and the End key reaches its physical end. Both onRangeChange.atBottom and debug atBottom include the footer. Debug totalHeight reports the full content extent on the active axis; averageItemHeight and counts remain row-only.

Observing the visible range

onRangeChange delivers a { start, end, atTop, atBottom } snapshot whenever the rendered item range or the scroll edges change (it also fires once after mount with the initial range). Use it for impression/analytics tracking, URL sync, sticky toolbars, or scroll-position persistence — no need to enable debug. start/end include the render buffer.

<SvelteVirtualList
    {items}
    onRangeChange={({ start, end, atTop, atBottom }) => {
        console.log(`rendering ${start}..${end}`, { atTop, atBottom })
    }}
>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>

Programmatic Scrolling

Scroll to any item in the list using the scroll method. Useful for jump-to-item navigation, search results, and more.

<script lang="ts">
    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
    let listRef
    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))

    function goToItem5000() {
        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
    }

    function restoreScrollPosition() {
        listRef.scrollToOffset({ offset: 12345, smoothScroll: false })
    }
</script>

<button onclick={goToItem5000}> Scroll to item 5000 </button>
<button onclick={restoreScrollPosition}> Restore scroll position </button>
<SvelteVirtualList {items} bind:this={listRef}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>

scroll() Options

| Option | Type | Default | Description | | --------------------- | ------------------------------------------------------ | -------- | --------------------------------------- | | index | number | Required | The item index to scroll to (0-based) | | smoothScroll | boolean | true | Use smooth scrolling animation | | shouldThrowOnBounds | boolean | true | Throw if index is out of bounds | | align | 'auto' \| 'top' \| 'bottom' \| 'nearest' \| 'center' | 'auto' | Where to align the item in the viewport |

Alignment options:

• 'auto' - Only scroll if not visible, align to nearest edge
• 'top' - Always align to the top
• 'bottom' - Always align to the bottom
• 'nearest' - Scroll as little as possible to bring the item into view
• 'center' - Center the item in the viewport, clamped at the list edges

scrollToOffset() Options

Use scrollToOffset({ offset, smoothScroll }) to scroll to a raw pixel offset, such as restoring a persisted scroll position after navigation. The returned promise resolves after scrolling has visually finished.

| Option | Type | Default | Description | | -------------- | --------- | -------- | ------------------------------------------ | | offset | number | Required | Raw offset in pixels along the active axis | | smoothScroll | boolean | true | Use smooth scrolling animation |

Horizontal and responsive orientation

Use orientation="horizontal" for an LTR horizontal list. The prop is reactive, so a keyed list can switch axes at a breakpoint while retaining the same logical visible item. Measurements are axis-specific and are cleared during the switch.

<SvelteVirtualList
    {items}
    itemKey={(item) => item.id}
    orientation={mobile ? 'horizontal' : 'vertical'}
    defaultEstimatedItemSize={120}
>
    {#snippet renderItem(item)}<article>{item.title}</article>{/snippet}
</SvelteVirtualList>

start/end, nearest, center, scrollToOffset(), range callbacks, and infinite loading follow the active axis. In horizontal mode Left/Right scroll by one line; Home/End go to the logical edges; Page Up/Page Down and Space page the viewport. Up/Down and keys inside interactive children are left alone. RTL horizontal behavior is not supported in this release.

See the horizontal guide or open the interactive 10,000-item example to switch between horizontal, vertical, and responsive modes.

Infinite Scroll

Load more data automatically as users scroll near the end of the list. Perfect for paginated APIs, infinite feeds, and activity logs.

<script lang="ts">
    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'

    let items = $state([...initialItems])
    let hasMore = $state(true)

    async function loadMore() {
        const newItems = await fetchMoreItems()
        items = [...items, ...newItems]
        if (newItems.length === 0) {
            hasMore = false
        }
    }
</script>

<SvelteVirtualList {items} onLoadMore={loadMore} loadMoreThreshold={20} {hasMore}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>

Infinite Scroll Behavior

• Triggers when scrolling near the end of the list
• Automatically triggers on mount if initial items are below threshold
• Prevents concurrent onLoadMore calls while loading
• Works with both sync and async callbacks

Integration Guides

• Infinite Scroll with Convex - Real-time data + pagination with Convex backend

Performance Considerations

• The bufferSize prop affects memory usage and scroll smoothness
• Items are measured and cached for optimal performance
• Dynamic height calculations happen automatically
• Resize observers handle container/content changes
• Virtual DOM updates are batched for efficiency

Testing

Unit Tests (Vitest)

# Run unit tests with coverage
pnpm test

# Run specific test files
pnpm vitest src/lib/utils/throttle.test.ts

E2E Tests (Playwright)

# Install Playwright browsers (one-time setup)
npx playwright install

# Run all e2e tests
pnpm run test:e2e

# Run specific e2e test
npx playwright test tests/docs-visit.spec.ts --project=chromium

# Debug mode
npx playwright test --debug

Project Structure

This is a PNPM workspace with two packages:

1. ./ - Main Svelte Virtual List component package
2. ./docs - Documentation site with live demos and examples

Development Commands

# Install dependencies for both packages
pnpm install

# Start development server
pnpm dev

# Start both package and docs
pnpm run dev:all

# Build package
pnpm run build

# Check TypeScript/Svelte
pnpm run check

# Format and lint code (uses Trunk)
trunk fmt
trunk check

# Run all tests
pnpm test:all

This project uses Trunk for formatting and linting. Trunk manages tool versions and runs checks automatically via pre-commit hooks.

Svelte 5 ecosystem

Part of the Humanspeak family of runes-native Svelte 5 packages:

| Package | Description | | --- | --- | | @humanspeak/svelte-markdown | Runtime markdown renderer for Svelte | | @humanspeak/svelte-virtual-list — this package | Virtual scrolling for Svelte | | @humanspeak/svelte-motion | Framer Motion for Svelte 5 | | @humanspeak/svelte-headless-table | Headless data tables for Svelte | | @humanspeak/svelte-virtual-chat | Virtual chat viewport for Svelte 5 | | @humanspeak/svelte-diff | Diff comparison for Svelte | | @humanspeak/svelte-purify | HTML sanitisation for Svelte | | @humanspeak/memory-cache | In-memory cache for TypeScript | | @humanspeak/svelte-json-view-lite | JSON tree viewer for Svelte 5 | | @humanspeak/svelte-scoped-props | Scoped class props for Svelte |

License

MIT © Humanspeak, Inc.

Credits

Made with ❤️ by Humanspeak