README.md

svelte-virtuallists

Keep your page efficient and fast: only shows the visible items!

About • Features • Usage • Demos • Samples

About

Keep your page efficient and fast: only shows the visible items, instead of displaying all your data in large lists.

This package originated from svelte-tiny-virtual-list and was modified to support Svelte 5, improved model handling, types, bug fixes, and overall project enhancement. Many thanks to the original author.

Features

• ❺➎⓹ Svelte 5+ only Build for Svelte 5+ in Typescript.

• 🚀 Performant Render millions of items, without breaking a sweat.

• 🛠 Configurable Customize width, heigh, position, style, content.

• 💠 Layout Control Support fixed and variables sizing, dynamic loading along with vertical and horizontal lists.

• 🧩 Programming Interface Set list positions and properties, and respond promptly to events.

• 💼 Small Compact and dependency free – Only ~5kb when compressed.

Usage

This component can be used two different ways:

• 🤖 As a scrollable listover a large number of items, optionally read incrementally.

• 🧠 As a fondation for more complex components - TreeViews and DataGrids.

Browser Support

Latest ✔	Latest ✔	Latest ✔	Latest ✔	Latest ✔	11 ✔

Star History

Demos

• REPL Demo
• More complex demos and examples

Samples

<script>
	import { VirtualList } from 'svelte-virtuallists';

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

<VirtualList width="100%" height={600} model={data} modelCount={data.length} itemSize={50}>
	{#snippet slot({ item, style, index })}
		<div class="row" {style}>
			Item: {item}, Row: #{index}
		</div>
	{/snippet}
</VirtualList>

You can also perform dynamic loading with a PartialLoader.

TODO: explain that model vs views, which translates into model and items

Props

The component accepts the following properties

Property	Type	Required?	Description
width	number or string*	✓	Width of List. This property will determine the number of rendered items when scrollDirection is 'horizontal'.
height	number or string*	✓	Height of List. This property will determine the number of rendered items when scrollDirection is 'vertical'.
model	any[]	✓	the model, the data for the items to display in the list.
modelCount	number	✓	The number of items you want to render.
itemSize	`number	number[]	(index: number) => number`
row	(r:RowAttributes) => SnippetResult	✓	Snippet called to render every item, see description below.
scrollDirection	string		Whether the list should scroll vertically or horizontally. One of 'vertical' (default) or 'horizontal'.
scrollOffset	number		Can be used to control the scroll offset; Also useful for setting an initial scroll offset.
scrollToIndex	number		Item index to scroll to (by forcefully scrolling if necessary).
scrollToAlignment	string		Used in combination with scrollToIndex, this prop controls the alignment of the scrolled to item. One of: 'start', 'center', 'end' or 'auto'. Use 'start' to always align items to the top of the container and 'end' to align them bottom. Use 'center' to align them in the middle of the container. 'auto' scrolls the least amount possible to ensure that the specified scrollToIndex item is fully visible.
scrollToBehaviour	string		Used in combination with scrollToIndex, this prop controls the behaviour of the scrolling. One of: 'auto', 'smooth' or 'instant' (default).
windowOverPadding	number		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		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		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.

* height must be a number when scrollDirection is 'vertical'. Similarly, width must be a number if scrollDirection is 'horizontal' _** model is stored, items are rendered

Snippets

• header - a snippet for the elements that should appear at the top of the list
• footer - a snippet for the elements that should appear at the bottom of the list
• slot - a required snipper property called to render each row of the list with the signature slot(r:RowAttributes<T>)

export interface RowAttributes<T> {
  item: T // the element from the model array to be rendered
	index: number; // Item index
	style: string; //  Item style, must be applied to the slot (look above for example)
}

for instance,

<VirtualList  ...>
  {#snippet slot({ item, style, index }:RowAttributes)}
    <div class="row" {style}>
      Item: {item}, Row: #{index}
    </div>
  {/snippet}
 </VirtualList>

Events

• onAfterScroll - Fired after handling the scroll event

Accepts a function with the following signature (event: AfterScrollEvent) => void

export interface AfterScrollEvent {
	type: 'range.update';
	// either the value of `wrapper.scrollTop` or `wrapper.scrollLeft`
	offset: number | string;
	// the original event
	event: Event;
}

• onVisibleRangeUpdate - Fired when the visible items are updated

Accepts a function with the following signature (range: VirtualRange) => void

export interface VirtualRangeEvent {
	type: 'scroll.update';
	start: number; //Index of the first visible item
	end: number; //Index of the last visible item
}

Contributing

Please read CODE OF CONDUCT and the CONTRIBUTION guide for more details.