## 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](https://github.com/clauderic/react-tiny-virtual-list) and uses most of its code and functionality!
### 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`](https://github.com/Skayo/svelte-infinite-loading) compatibility
## Installation
> If you're using this component in a Sapper application, make sure to install the package to `devDependencies`!
> [More Details](https://github.com/sveltejs/sapper-template#using-external-components)
With npm:
```shell
$ npm install svelte-tiny-virtual-list
```
With yarn:
```shell
$ yarn add svelte-tiny-virtual-list
```
With [pnpm](https://pnpm.js.org/) (recommended):
```shell
$ npm i -g pnpm
$ pnpm install svelte-tiny-virtual-list
```
From CDN (via [unpkg](https://unpkg.com/)):
```html
```
## Usage
```svelte
Letter: {data[index]}, Row: #{index}
```
Also works pretty well with [`svelte-infinite-loading`](https://github.com/Skayo/svelte-infinite-loading):
```svelte
Letter: {data[index]}, Row: #{index}
```
### Props
| Property | Type | Required? | Description |
| ----------------- | ------------------------------------------------- | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| width | `number \| string`\* | ✓ | Width of List. This property will determine the number of rendered items when scrollDirection is `'horizontal'`. |
| height | `number \| string`\* | ✓ | Height of List. This property will determine the number of rendered items when scrollDirection is `'vertical'`. |
| itemCount | `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` |
| 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). |
| stickyIndices | `number[]` | | An array of indexes (eg. `[0, 10, 25, 30]`) to make certain items in the list sticky (`position: sticky`) |
| overscanCount | `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'`_
### Slots
- `item` - Slot for each item
- Props:
- `index: number` - Item index
- `style: string` - Item style, must be applied to the slot (look above for example)
- `header` - Slot for the elements that should appear at the top of the list
- `footer` - Slot for the elements that should appear at the bottom of the list (e.g. `InfiniteLoading` component from `svelte-infinite-loading`)
### Events
- `afterScroll` - Fired after handling the scroll event
- `detail` Props:
- `event: ScrollEvent` - The original scroll event
- `offset: number` - Either the value of `wrapper.scrollTop` or `wrapper.scrollLeft`
- `itemsUpdated` - Fired when the visible items are updated
- `detail` Props:
- `start: number` - Index of the first visible item
- `end: number` - Index of the last visible item
### Methods
- `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.
#### Use the methods like this:
```svelte
Letter: {data[index]}, Row: #{index}
```
### Styling
You can style the elements of the virtual list like this:
```svelte
