@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 scroll
- ♾️ Infinite scroll support with onLoadMore

scroll: Programmatic Scrolling

You can now programmatically scroll to any item in the list using the scroll method. This is useful for chat apps, jump-to-item navigation, and more. You can check the usage in src/routes/tests/scroll. Thank you for the feature request!

$3

``svelte


Scroll to item 5000

{#snippet renderItem(item)}


- scroll(options: { index: number; smoothScroll?: boolean; shouldThrowOnBounds?: boolean; align?: 'auto' | 'top' | 'bottom' | 'nearest' })
- 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)
- align: Where to align the item in the viewport:
- 'auto' (default): Only scroll if not visible, align to top or bottom as appropriate
- 'top': Always align to the top
- 'bottom': Always align to the bottom
- 'nearest': Scroll as little as possible to bring the item into view (like native scrollIntoView({ block: 'nearest' }))

#### Usage Examples

`svelte
listRef.scroll({ index: 5000, align: 'nearest' })}>
Scroll to item 5000 (nearest)

`

Infinite Scroll

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

`svelte



{#snippet renderItem(item)}


| Prop | Type | Default | Description |
| ------------------- | ----------------------------- | ------- | ---------------------------------------------------- |
| onLoadMore | () => void \| Promise | - | Callback when more data is needed (supports async) |
| loadMoreThreshold | number | 20 | Number of items from the end to trigger onLoadMore |
| hasMore | boolean | true | Set to false when all data has been loaded |

$3

- 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
- Supports both topToBottom and bottomToTop modes

$3

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

Installation

`bash


Using npm

`svelte



{#snippet renderItem(item)}


`svelte


Use mode="bottomToTop" for chat-like lists anchored to the bottom. Programmatic scrolling uses the same API as top-to-bottom lists:

`svelte



listRef.scroll({ index: messages.length - 1, align: 'bottom' })}>
Jump to latest

`

Props

| Prop | Type | Default | Description |
| ---------------------------- | -------------------------------- | --------------- | ----------------------------------------------------------------------------- |
| items | T[] | Required | Array of items to render |
| defaultEstimatedItemHeight | number | 40 | Initial height estimate used until items are measured |
| mode | 'topToBottom' \| 'bottomToTop' | 'topToBottom' | Scroll direction and anchoring behavior |
| 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 |
| 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 | - | 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 |

Testing

$3

`bash


Run unit tests with coverage

`bash


Install Playwright browsers (one-time setup)

`bash


Start development server

- 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

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

$3

`bash


Install dependencies for both packages

License

MIT © Humanspeak, Inc.

Credits

Made with ❤️ by Humanspeak