@tutorlatin/svelte-tiny-virtual-list

@tutorlatin/svelte-tiny-virtual-list

A tiny but mighty list virtualization library, with zero dependencies 💪

About • Features • Installation • Usage • Examples • License

About

Instead of rendering all your data in a huge list, the virtual list component just renders the items that are visible, keeping your page nice and light.
This is heavily inspired by react-tiny-virtual-list and uses most of its code and functionality!

This is a maintained fork of svelte-tiny-virtual-list.

Features

• Tiny & dependency free – Only ~5kb gzipped
• Render millions of items, without breaking a sweat
• Scroll to index or set the initial scroll offset
• Supports fixed or variable heights/widths
• Vertical or Horizontal lists
• svelte-infinite-loading compatibility

Installation

With npm:

$ npm install @tutorlatin/svelte-tiny-virtual-list

With yarn:

$ yarn add @tutorlatin/svelte-tiny-virtual-list

With pnpm:

$ pnpm install @tutorlatin/svelte-tiny-virtual-list

Usage

<script>
	import VirtualList from '@tutorlatin/svelte-tiny-virtual-list';

	const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
</script>

<VirtualList height={600} itemCount={data.length} itemSize={50}>
	{#snippet item({ style, index })}
		<div {style}>
			Letter: {data[index]}, Row: #{index}
		</div>
	{/snippet}
</VirtualList>

Also works pretty well with svelte-infinite-loading:

<script>
	import VirtualList from '@tutorlatin/svelte-tiny-virtual-list';
	import InfiniteLoading from 'svelte-infinite-loading';

	let data = $state(['A', 'B', 'C', 'D', 'E', 'F' /* ... */]);

	function infiniteHandler({ detail: { complete, error } }) {
		try {
			// Normally you'd make an http request here...

			const newData = ['G', 'H', 'I', 'J', 'K', 'L' /* ... */];

			data = [...data, ...newData];
			complete();
		} catch (e) {
			error();
		}
	}
</script>

<VirtualList height={600} itemCount={data.length} itemSize={50}>
	{#snippet item({ style, index })}
		<div {style}>
			Letter: {data[index]}, Row: #{index}
		</div>
	{/snippet}

	{#snippet footer()}
		<div>
			<InfiniteLoading on:infinite={infiniteHandler} />
		</div>
	{/snippet}
</VirtualList>

Props

Property	Type	Default	Description
itemCount	number	REQUIRED	The number of items you want to render.
itemSize	number | number[] | (index: number) => number	REQUIRED	Either a fixed height/width (depending on the scrollDirection), an array containing the heights of all the items in your list (⚠ if passing an array, do not mutate in place: replace the array reference to trigger updates), or a function that returns the height of an item given its index: (index: number) => number.
width	number | string	'100%'	Width of the list view box. When scrollDirection is 'horizontal', this property determines the number of rendered items.
height	number | string	'100%'	Height of the list view box. When scrollDirection is 'vertical', this property determines the number of rendered items.
scrollDirection	'vertical' | 'horizontal'	'vertical'	Whether the list should scroll vertically or horizontally.
scrollOffset	number	0	Used to control the scroll offset, but also useful for setting an initial scroll offset.
scrollToIndex	number	-1	Item index to scroll to (by forcefully scrolling if necessary).
scrollToAlignment	'start' | 'center' | 'end' | 'auto'	'start'	Used in combination with scrollToIndex, this prop controls the alignment of the scrolled to item. Use 'auto' to scroll the least amount required to ensure that the specified scrollToIndex item is fully visible.
scrollToBehaviour	'smooth' | 'instant' | 'auto'	'instant'	Used in combination with scrollToIndex, this prop controls the behaviour of the scrolling. See: [Element: scroll() method - Web APIs
stickyIndices	number[]	[]	An array of indexes (eg. [0, 10, 25, 30]) to make certain items in the list sticky (position: sticky)
overscanCount	number	3	Number of extra buffer items to render above/below the visible items. Tweaking this can help reduce scroll flickering on certain browsers/devices.
estimatedItemSize	number	0	Used to estimate the total size of the list before all of its items have actually been measured. The estimated total height is progressively adjusted as items are rendered.
getKey	((index: number) => any) | null	undefined	Function that returns the key of an item in the list, which is used to uniquely identify an item. This is useful for dynamic data coming from a database or similar. By default, it's using the item's index.
onAfterScroll	({ event: ScrollEvent, offset: number }) => void	undefined	Function that fires after handling the scroll event. Props: event: ScrollEvent - The original scroll event, offset: number - Either the value of wrapper.scrollTop or wrapper.scrollLeft
onListItemsUpdate	({ start: number, end: number }) => void	undefined	Function that fires when the visible items are updated. Props: start: number - Index of the first visible item, end: number - Index of the last visible item.

Snippets

• item - Snippet for each item
  • Prop: { index, style }
    • index: number - Item index
    • style: string - Item style, must be applied to the snippet (look above for example)
• header - Snippet for the elements that should appear at the top of the list
• footer - Snippet for the elements that should appear at the bottom of the list (e.g. InfiniteLoading component from svelte-infinite-loading)

Styling

You can style the elements of the virtual list like this:

<script>
	import VirtualList from '@tutorlatin/svelte-tiny-virtual-list';

	const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
</script>

<div class="list">
	<VirtualList height={600} itemCount={data.length} itemSize={50}>
		{#snippet item({ style, index })}
			<div {style}>
				Letter: {data[index]}, Row: #{index}
			</div>
		{/snippet}
	</VirtualList>
</div>

<style>
	.list :global(.virtual-list-wrapper) {
		background-color: yellow;
		/* ... */
	}

	.list :global(.virtual-list-inner) {
		background-color: red;
		/* ... */
	}

	.list {
		--virtual-list-sticky-bg: red;
	}
</style>

Examples / Demo

• Basic setup
  • Elements of equal height
  • Variable heights
  • Horizontal list
• Controlled props
  • Scroll to index
  • Controlled scroll offset
• Hacker News using svelte-infinite-loading

License

MIT License