If you are looking for a vue component which support big data list with high scroll performance, now you are in the right place!

• Advantages
• Live demos
• How it works
• Simple usage
  • Using by npm module
  • Using by script include
• Attentions
• Props type
• Public methods
• Special scenes
  • About variable mode
  • About item mode
• Contributions
• Changelogs

Advantages

• Tiny and very very easy to use.

• Big data list with high performance.

• Support fixed height and variable height.

• Support set the scroll index or offset to any.

• Event scroll, reach top and bottom can be detected.

Live demos

• Scroll with 100,000 finite data.

• Scroll with request infinite data.

• Scroll with variable height mode.

How it works

Simple usage

Using by npm module:

npm install vue-virtual-scroll-list --save

<template>
    <div>
        <virtual-list :size="40" :remain="8">
            <item v-for="item of items" :key="item.id" />
        </virtual-list>
    </div>
</template>

<script>
    import item from '../item.vue'
    import virtualList from 'vue-virtual-scroll-list'

    export default {
        data () {
            return {
                items: [ {id: 1}, {id: 2}, {id: 3}, ... ]
            }
        },
        components: { item, 'virtual-list': virtualList }
    }
</script>

Using by script include:

<script src="https://unpkg.com/[email protected]/dist/vue.js"></script>
<script src="https://tangbc.github.io/vue-virtual-scroll-list/index.js"></script>

<div id="app">
    <virtual-list :size="40" :remain="8" wtag="ul">
        <li class="item" v-for="(udf, index) of items" :key="index">Item: # {{ index }}</li>
    </virtual-list>
</div>

// Global name as `VirtualScrollList`
Vue.component('virtual-list', VirtualScrollList)

new Vue({
    el: '#app',
    data: {
        items: new Array(100000)
    }
})

Attentions

• Must assign the :key property on <item> component or dom frag with v-for directive.

• Consider use box-sizing: border-box on <item> if you want absolutely correct scroll height.

Props type

Prop	Type	Required	Description
size	Number	✓	Each list item height, in variable height mode, this prop just use to calculate the virtual-list outside container viewport height.
remain	Number	✓	How many items should be shown in virtual-list viewport, so size and remain determine the outside container viewport height (size × remian).
bench	Number	*	Default value is equal to remain, unreached items count, not show in virtual-list viewport but exist in real DOM, the larger the bench, the higher the scroll performance will achieved.
start	Number	*	Default value is 0, the initial scroll start index. It must be integer and in the range of list index, if invalid there will be effected as 0 or the last one.
offset	Number	*	Default value is 0, the initial scroll offset. If both start and offset are assigned at initialization, start is preferred.
debounce	Number	*	It's disabled by default, milliseconds of using debounce function to ensure scroll event doesn't fire so often that it bricks browser performance.
rtag	String	*	Default value is div, the virtual-list root element tag name, in all cases it's style is set to display: block;
wtag	String	*	Default value is div, the virtual-list item wrapper element tag name, in all cases it's style is set to display: block;
wclass	String	*	Default value is an empty string, the virtual-list item wrapper element class, if assign this prop, you better not to change it's CSS box model.
totop	Function	*	Called when virtual-list is scrolled to top, no param.
tobottom	Function	*	Called when virtual-list is scrolled to bottom, no param.
onscroll	Function	*	Called when virtual-list is scrolling, with param: (event, data).
variable	Function or Boolean	*	For using virtual-list in variable-mode. If assign Function, this prop is a variable height getter function which is called with param: (index) when each item is ready to be calculated. If assign Boolean, virtual-list will get each item variable height by it's inline style height automatic.
item	Component	*	For using virtual-list in item-mode. List item vue component, see details below.
itemdata	Array	*	For using virtual-list in item-mode. Prop data list or item slots assign to each item, see details below.
itemprop	Function	*	For using virtual-list in item-mode. Function call when each item is going to be rendered, see details below.

Public methods

Here are some usefull public methods you can call via ref:

• forceRender(): force render virtual-list if you need or make it refresh.

• updateVariable(index): update item height by index in variable height mode.

Special scenes

About variable mode

In variable-mode, prop size is still required. All the index variable height and scroll offset will be cached by virtual-list after the binary-search calculate, if you want to change anyone <item/> height from data, you should call virtual-list's updateVariable(index) method to clear the offset cache, refer to variable example source for detail.

If you assign variable as true, do not set inline style height inside <item/> component, you must set inline style height on <item/> component outside directly, such as:

<template>
    <div>
        <virtual-list :size="40" :remain="8" :variable="true">
            <item v-for="item of items" :key="item.id" :style="{ height: item.height + 'px' }" />
        </virtual-list>
    </div>
</template>

About item mode

Use item-mode can save a considerable amount of memory and performance, stats data check here: #87.

In this mode, prop item itemdata itemprop are both required, and you don't have to put <item/> with a v-for frag inside virtual-list, just assign it as prop item:

<template>
    <div>
        <virtual-list :size="40" :remain="8"
            :item="item"
            :itemdata="itemdata"
            :itemprop="itemprop"
        />
    </div>
</template>

<script>
    import itemComponent from '../item.vue'
    import virtualList from 'vue-virtual-scroll-list'

    export default {
        data () {
            return {
                item: itemComponent,
                itemdata: [ {id: 1}, {id: 2}, {id: 3}, ... ]
            }
        },
        methods: {
            // index: item index
            // data: item data get from itemdata array
            itemprop (index, data) {
                const id = { data }
                const itemProps = getItemProp(id)
                return {
                    props: itemProps // <item/> will receive prop with itemProps
                }
            }
        },
        components: { 'virtual-list': virtualList }
    }
</script>

Contributions

Welcome to improve vue-virtual-scroll-list with any issue, pull request or code review.

Changelogs

Maintain and update occasionally, for changes see release.

License

MIT License