@vylq/virtual-scroll

Props

items: list of items you want to display in the scroller.
direction (default: 'vertical'): scrolling direction, either 'vertical' or 'horizontal'.
itemSize (default: null): display height (or width in horizontal mode) of the items in pixels used to calculate the scroll size and position. If it is set to null (the default value), it will use variable size mode.
gridItems: display that many items on the same line to create a grid. You must put a value for itemSize to use this prop (dynamic sizes are not supported).
itemSecondarySize: size in pixels (width in vertical mode, height in horizontal mode) of the items in the grid when gridItems is set. If itemSecondarySize is not set, it will use the value of itemSize.
minItemSize: minimum size used if the height (or width in horizontal mode) of a item is unknown.
sizeField (default: 'size'): field used to get the item's size in variable size mode.
typeField (default: 'type'): field used to differentiate different kinds of components in the list. For each distinct type, a pool of recycled items will be created.
keyField (default: 'id'): field used to identify items and optimize managing rendered views.
pageMode (default: false): enable Page mode.
prerender (default: 0): render a fixed number of items for Server-Side Rendering (SSR).
buffer (default: 200): amount of pixel to add to edges of the scrolling visible area to start rendering items further away.
emitUpdate (default: false): emit a 'update' event each time the virtual scroller content is updated (can impact performance).
listClass (default: ''): custom classes added to the item list wrapper.
itemClass (default: ''): custom classes added to each item.
listTag (default: 'div'): the element to render as the list's wrapper.
itemTag (default: 'div'): the element to render as the list item (the direct parent of the default slot content).
itemGap (default: 0): the spacing for each item
itemsLimit (default: 1000): limit items for virtual scroll
diffCheckThreshold (default: 0): the maximum allowable difference between the lengths of the new items and old items arrays before triggering render items

Events

resize: emitted when the size of the scroller changes.
visible: emitted when the scroller considers itself to be visible in the page.
hidden: emitted when the scroller is hidden in the page.
update (startIndex, endIndex, visibleStartIndex, visibleEndIndex): emitted each time the views are updated, only if emitUpdate prop is true
scroll-start: emitted when the first item is rendered.
scroll-end: emitted when the last item is rendered.

Default scoped slot props

item: item being rendered in a view.
index: reflects each item's position in the items array
active: whether or not the view is active. An active view is considered visible and being positioned by Scroller. An inactive view is not considered visible and is hidden from the user. Any rendering-related computations should be skipped if the view is inactive.

Other Slots

<main>
  <slot name="before"></slot>
  <wrapper>
    <!-- Reused view pools here -->
    <slot name="empty"></slot>
  </wrapper>
  <slot name="after"></slot>
</main>

Example:

<Scroller
  class="scroller"
  :items="list"
  :item-size="32"
>
  <template #before>
    Hey! I'm a message displayed before the items!
  </template>

  <template v-slot="{ item }">
    <div class="user">
      {{ item.name }}
    </div>
  </template>
</Scroller>

Page mode

The page mode expands the virtual-scroller and uses the page viewport to compute which items are visible. That way, you can use it in a big page with HTML elements before or after (like a header and a footer). Set the page-mode prop to true:

<header>
  <menu></menu>
</header>

<Scroller page-mode>
  <!-- ... -->
</Scroller>

<footer>
  Copyright 2017 - Cat
</footer>

Variable size mode

⚠️ This mode can be performance heavy with a lot of items. Use with caution.

If the itemSize prop is not set or is set to null, the virtual scroller will switch to variable size mode. You then need to expose a number field on the item objects with the size of the item element.

⚠️ You still need to set the size of the items with CSS correctly (with classes for example).

Use the sizeField prop (default is 'size') to set the field used by the scroller to get the size for each item.

Example:

const items = [
  {
    id: 1,
    label: 'Title',
    size: 64,
  },
  {
    id: 2,
    label: 'Foo',
    size: 32,
  },
  {
    id: 3,
    label: 'Bar',
    size: 32,
  },
]

Buffer

You can set the buffer prop (in pixels) on the virtual-scroller to extend the viewport considered when determining the visible items. For example, if you set a buffer of 1000 pixels, the virtual-scroller will start rendering items that are 1000 pixels below the bottom of the scroller visible area, and will keep the items that are 1000 pixels above the top of the visible area.

The default value is 200.

<Scroller :buffer="200" />

Server-Side Rendering

The prerender props can be set as the number of items to render on the server inside the virtual scroller:

<Scroller
  :items="items"
  :item-size="42"
  :prerender="10"
>

VirtualScroller

This works just like the Scroller, but it can render items with unknown sizes!

Basic usage

<template>
  <VirtualScroller
    :items="items"
    :min-item-size="54"
    class="scroller"
  >
    <template v-slot="{ item, index, active }">
      <VirtualScrollerItem
        :item="item"
        :active="active"
        :size-dependencies="[
          item.message,
        ]"
        :data-index="index"
      >
        <div class="avatar">
          <img
            :src="item.avatar"
            :key="item.avatar"
            alt="avatar"
            class="image"
          >
        </div>
        <div class="text">{{ item.message }}</div>
      </VirtualScrollerItem>
    </template>
  </VirtualScroller>
</template>

<script>
export default {
  props: {
    items: Array,
  },
}
</script>

<style scoped>
.scroller {
  height: 100%;
}
</style>

Important notes

minItemSize is required for the initial render of items.
VirtualScroller won't detect size changes on its own, but you can put values that can affect the item size with size-dependencies on VirtualScrollerItem.
You don't need to have a size field on the items.

Props

Extends all the Scroller props.

It's not recommended to change sizeField prop since all the size management is done internally.

Events

Extends all the Scroller events.

Default scoped slot props

Extends all the Scroller scoped slot props.

Other slots

Extends all the Scroller other slots.

VirtualScrollerItem

The component that should wrap all the items in a VirtualScroller.

Props

item (required): the item rendered in the scroller.
active (required): is the holding view active in Scroller. Will prevent unnecessary size recomputation.
sizeDependencies: values that can affect the size of the item. This prop will be watched and if one value changes, the size will be recomputed. Recommended instead of watchData.
watchData (default: false): deeply watch item for changes to re-calculate the size (not recommended, can impact performance).
tag (default: 'div'): element used to render the component.
emitResize (default: false): emit the resize event each time the size is recomputed (can impact performance).

Events

resize: emitted each time the size is recomputed, only if emitResize prop is true.