Keep your page efficient and fast: only shows the visible items!
About • Features • Usage • Demos • Samples
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.
-
❺➎⓹ 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 Headless, support fixed and variables sizing, along with vertical and horizontal lists.
-
🧩 Programming Interface Set positions and properties, raises events on state mutation.
-
💼 Small Compact and dependency free – Only ~5kb when compressed.
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.
Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11 ✔ |
<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
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
header
- a snippet for the elements that should appear at the top of the listfooter
- a snippet for the elements that should appear at the bottom of the listslot
- a required snipper property called to render each row of the list with the signatureslot(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>
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
}
Please read CODE OF CONDUCT and the CONTRIBUTION guide for more details.