@humanspeak/svelte-virtual-list
TypeScript icon, indicating that this package has built-in type declarations

0.2.4 • Public • Published

@humanspeak/svelte-virtual-list

NPM version Build Status Coverage Status License Downloads CodeQL Code Style: Trunk TypeScript Types Maintenance

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

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

Prop Type Default Description
items T[] Required Array of items to render
defaultItemHeight number 40 Initial height for items before measurement
mode 'topToBottom' | 'bottomToTop' 'topToBottom' Scroll direction
bufferSize number 20 Number of items to render outside viewport
debug boolean false Enable debug logging and visualizations
containerClass string '' Class for outer container
viewportClass string '' Class for scrollable viewport
contentClass string '' Class for content wrapper
itemsClass string '' Class for items container

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

Package Sidebar

Install

npm i @humanspeak/svelte-virtual-list

Weekly Downloads

31

Version

0.2.4

License

MIT

Unpacked Size

62.7 kB

Total Files

17

Last publish

Collaborators

  • humanspeakadmin