jonasgeiler/svelte-tiny-virtual-list

svelte-tiny-virtual-list

A tiny but mighty list virtualization library, with zero dependencies 💪

About • Features • Installation • Usage • Examples • License

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 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 compatibility

Installation

If you're using this component in a Sapper application, make sure to install the package to devDependencies!
More Details

With npm:

$ npm install svelte-tiny-virtual-list

With yarn:

$ yarn add svelte-tiny-virtual-list

With pnpm (recommended):

$ npm i -g pnpm
$ pnpm install svelte-tiny-virtual-list

From CDN (via unpkg):

<!-- UMD -->
<script src="https://unpkg.com/svelte-tiny-virtual-list@^1/dist/svelte-tiny-virtual-list.js"></script>

<!-- ES Module -->
<script src="https://unpkg.com/svelte-tiny-virtual-list@^1/dist/svelte-tiny-virtual-list.mjs"></script>

Usage

<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}>
  <div slot="item" let:index let:style {style}>
    Letter: {data[index]}, Row: #{index}
  </div>
</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 = ['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}>
  <div slot="item" let:index let:style {style}>
    Letter: {data[index]}, Row: #{index}
  </div>

  <div slot="footer">
    <InfiniteLoading on:infinite={infiniteHandler} />
  </div>
</VirtualList>

Props

* 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:

<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 on:click={handleClick}>Recompute Sizes</button>

<VirtualList
        bind:this={virtualList}
        width="100%"
        height={600}
        itemCount={data.length}
        itemSize={50}>
  <div slot="item" let:index let:style {style}>
    Letter: {data[index]}, Row: #{index}
  </div>
</VirtualList>

Styling

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}>
    <div slot="item" let:index let:style {style}>
      Letter: {data[index]}, Row: #{index}
    </div>
  </VirtualList>
</div>

<style>
  .list :global(.virtual-list-wrapper) {
    background-color: #0f0;
    /* ... */
  }
  
  .list :global(.virtual-list-inner) {
    background-color: #f00;
    /* ... */
  }
</style>

Examples / Demo

• Basic setup
  • Elements of equal height
  • Variable heights
  • Horizontal list
• Controlled props
  • Scroll to index
  • Controlled scroll offset
• Hacker News using svelte-infinite-loading

License

MIT License