A tiny but mighty list virtualization library, with zero dependencies 💪
About • Features • Installation • Usage • Examples • License
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!
svelte-infinite-loading
compatibilityWith npm:
$ npm install svelte-tiny-virtual-list
With yarn:
$ yarn add svelte-tiny-virtual-list
With pnpm:
$ pnpm install svelte-tiny-virtual-list
<script>
import VirtualList from 'svelte-tiny-virtual-list';
const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
</script>
<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
{#snippet children({ style, index })}
<div {style}>
Letter: {data[index]}, Row: #{index}
</div>
{/snippet}
</VirtualList>
Also works pretty well with svelte-infinite-loading
:
<script>
import VirtualList from '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 width="100%" height={600} itemCount={data.length} itemSize={50}>
{#snippet children({ style, index })}
<div {style}>
Letter: {data[index]}, Row: #{index}
</div>
{/snippet}
{#snippet footer()}
<div>
<InfiniteLoading on:infinite={infiniteHandler} />
</div>
{/snippet}
</VirtualList>
Property | Type | Default | Description |
---|---|---|---|
width | number | string |
REQUIRED or '100%' |
Width of the list view box. When scrollDirection is 'horizontal' , this property is required to be a number and determines the number of rendered items. |
height | number | string |
REQUIRED or '100%' |
Height of the list view box. When scrollDirection is 'vertical' , this property is required to be a number and determines the number of rendered items. |
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, or a function that returns the height of an item given its index: (index: number) => number . |
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. |
children
- Snippet for each item{ index, style }
index: number
- Item indexstyle: 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 listfooter
- Snippet for the elements that should appear at the bottom of the list (e.g. InfiniteLoading
component from svelte-infinite-loading
)recomputeSizes(startIndex: number)
- This method force recomputes the item sizes after the specified index (these are normally cached).VirtualList
has no way of knowing when its underlying data has changed, since it only receives a itemSize property. If the itemSize is a number
, this isn't an issue, as it can compare before and after values and automatically call recomputeSizes
internally.
However, if you're passing a function to itemSize
, that type of comparison is error prone. In that event, you'll need to call recomputeSizes
manually to inform the VirtualList
that the size of its items has changed.
<script>
import { onMount } from 'svelte';
import VirtualList from 'svelte-tiny-virtual-list';
const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
let virtualList;
function handleClick() {
virtualList.recomputeSizes(0);
}
</script>
<button onclick={handleClick}>Recompute Sizes</button>
<VirtualList
bind:this={virtualList}
width="100%"
height={600}
itemCount={data.length}
itemSize={50}
>
{#snippet children({ style, index })}
<div {style}>
Letter: {data[index]}, Row: #{index}
</div>
{/snippet}
</VirtualList>
You can style the elements of the virtual list like this:
<script>
import VirtualList from 'svelte-tiny-virtual-list';
const data = ['A', 'B', 'C', 'D', 'E', 'F' /* ... */];
</script>
<div class="list">
<VirtualList width="100%" height={600} itemCount={data.length} itemSize={50}>
{#snippet children({ style, index })}
<div {style}>
Letter: {data[index]}, Row: #{index}
</div>
{/snippet}
</VirtualList>
</div>
<style>
.list :global(.virtual-list-wrapper) {
background-color: #0f0;
/* ... */
}
.list :global(.virtual-list-inner) {
background-color: #f00;
/* ... */
}
</style>