svelte-virtuallists
v1.2.2
Published
A component that renders only what is visible
Downloads
341
Readme
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
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
| ✓ | 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
|
| 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 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>
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.