Minimalistic and tiny Vue.js scroll list components for an endless amount of data

Note: Version 3.x of v-endless-list is compatible with Vue 3 only. Install version 2.x if you use Vue 2.

Provides two components:

• v-endless-virtual-list: Renders only items in the viewport for performance. Supports lazy loading and jumping to given items. Requires fixed item height. Recommended for extremely large data sets.

• v-endless-lazy-list: Simple list with lazy loading. Supports variable height items but is less efficient for large data sets (slower when scrolling far down). Recommended for small to medium data sets.

• Installation
• Usage
• API

Install v-endless-list:

npm install --save v-endless-list

Then import it in your project:

import { createApp, h } from 'vue';
import vEndlessList from 'v-endless-list';

const app = Vue.createApp(App);
app.use(vEndlessList, { h });
app.mount('#app');

Or include the files via <script> tag:

<script src="https://unpkg.com/[email protected]/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/v-endless-list/dist/vEndlessList.min.js"></script>
<script>
    const app = Vue.createApp(App);
    app.use(vEndlessList, { h: Vue.h });
    app.mount('#app');
</script>

Most basic usage example for both components (read about Vue Scoped Slots to understand the syntax):

<v-endless-virtual-list :items="items" item-height="100">
    <template #default="item">
        <div>{{ item }}</div>
    </template>
</v-endless-virtual-list>

<v-endless-lazy-list :items="items">
    <template #default="item">
        <div>{{ item }}</div>
    </template>
</v-endless-lazy-list>

Advanced usage example for both components:

<v-endless-virtual-list
    :items="items"
    height="50vh"
    item-height="100"
    @reached-bottom="lazyLoadItems()"
>
    <template #empty-list>
        <b>No items in this list.</b>
    </template>
    <template #default="item">
        <my-component :my-data="item.myData"></my-component>
    </template>
</v-endless-virtual-list>

<v-endless-lazy-list
    :items="items"
    height="50vh"
    increment="100"
    loading-threshold="42"
    list-change-behavior="keep"
    @reached-top="onReachedTop()"
>
    <template #empty-list>
        <b>No items in this list.</b>
    </template>
    <template #default="item">
        <my-component :my-data="item.myData"></my-component>
    </template>
</v-endless-lazy-list>

Also check the demo in the demo directory. You can run the demos with npm run demo. Open your browser at http://127.0.0.1:1337/demo.

• items: Array, required. List of items you want to display.
• item-height: Number, required. Height of an individual list item in pixels. Overflow will be hidden.
• height: String, optional, default "100%". CSS height of the entire list component.

• default (scoped slot, required): Component to render for each list item, receives the list item in the slot scope.
• empty-list (optional): Text or content to show when there are no items in the list.

• reached-top: Emitted when the list is scrolled to the very top.
• reached-bottom: Emitted when the list is scrolled to the very bottom. Can be used for lazy loading new items.

• scrollTo: Can be used to scroll the list to a given item. Valid parameters are:
  • "top": scroll to top
  • "bottom": scroll to bottom
  • index (Number): scroll to the item with the given index

• items: Array, required. List of items you want to display.
• height: String, optional, default "100%". CSS height of the entire list component.
• increment: Number, optional, default 10. Number of items to add to the end of the list on lazy loading.
• loadingThreshold: Number, optional, default 10. Threshold after which lazy loading is triggered, i.e. number of pixels before reaching the end of the list when scrolling.
• listChangeBehavior: Either "reset" or "keep", optional, default "reset". Behavior of the list when the data set length changes.
  • "reset": Reset the number of items to increment and scroll to the top.
  • "keep": Keep the number of currently shown items as well as scroll state.

• default (scoped slot, required): Component to render for each list item, receives the list item in the slot scope.
• empty-list (optional): Text or content to show when there are no items in the list.

• reached-top: Emitted when the list is scrolled to the very top.
• reached-bottom: Emitted when the list is scrolled to the very bottom.

• scrollTo: Can be used to scroll the list to a given item. Valid parameters are:
  • "top": scroll to top
  • "bottom": scroll to bottom. Forces loading of all items. Note that this can have a huge performance impact and might freeze the browser temporarily. Use with caution.
  • index (Number): scroll to the item with the given index. See note on performance above.