@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
• 🔄 Bi-directional scrolling support (top-to-bottom and bottom-to-top)
• 🔄 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 scrollToIndex

scrollToIndex: Programmatic Scrolling

You can now programmatically scroll to any item in the list using the scrollToIndex method. This is useful for chat apps, jump-to-item navigation, and more. Thank you for the feature request.

Usage Example

<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() {
        // Scroll to item 5000 with smooth scrolling
        listRef.scrollToIndex(5000, true)
    }
</script>

<button on:click={goToItem5000}> Scroll to item 5000 </button>
<SvelteVirtualList {items} bind:this={listRef}>
    {#snippet renderItem(item)}
        <div>{item.text}</div>
    {/snippet}
</SvelteVirtualList>

API

• scrollToIndex(index: number, smoothScroll = true, shouldThrowOnBounds = true)
  • index: The item index to scroll to (0-based)
  • smoothScroll: If true, uses smooth scrolling (default: true)
  • shouldThrowOnBounds: If true, throws if index is out of bounds (default: true)

Installation

npm install @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>

Advanced Features

Chat Application Example

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

    type Message = {
        id: number
        text: string
        timestamp: Date
    }

    const messages: Message[] = Array.from({ length: 100 }, (_, i) => ({
        id: i,
        text: `Message ${i}`,
        timestamp: new Date()
    }))
</script>

<div style="height: 500px;">
    <SvelteVirtualList items={messages} mode="bottomToTop" debug>
        {#snippet renderItem(message)}
            <div class="message-container">
                <p>{message.text}</p>
                <span class="timestamp">
                    {message.timestamp.toLocaleString()}
                </span>
            </div>
        {/snippet}
    </SvelteVirtualList>
</div>

Props

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

License

MIT © Humanspeak, Inc.

Credits

Made with ♥ by Humanspeak