async-virtual-scroll - Vue3 Asynchronous Virtual Scroll Component

High-performance virtual scroll component supporting dynamic height rendering, optimized for large data list display

简体中文

react version

Features

• 🚀 Efficient rendering of massive datasets
• 📏 Supports fixed height and dynamic height
• 🔍 Automatically calculates visible area content
• 🔄 Built-in scroll optimization and buffer mechanism
• ⏳ Smart loading state management
• 🔧 Highly customizable configuration

Installation & Usage

Install

npm install @jason12306/vue-async-virtual-scroll

Basic Usage

<template>
  <div class="test-container">
    <div class="scroll-container">
      <async-virtual-scroll v-model="show" :data="items" :item-size="60">
        <template v-slot="{ item, dataUid }">
          <div class="list-item" :data-uid="dataUid" :style="{ backgroundColor: item.color }">
            {{ item.id }}. {{ item.text }}
          </div>
        </template>
      </async-virtual-scroll>
    </div>
  </div>
</template>

<script setup lang="ts">
  import { ref, onMounted } from 'vue'
  import AsyncVirtualScroll from '@jason12306/vue-async-virtual-scroll'
  import '@jason12306/vue-async-virtual-scroll/vue-async-virtual-scroll.css'

  const show = ref(false)
  const num = 500
  const items = ref([])

  for (let i = 1; i <= num; i++) {
    items.value.push({
      id: i,
      text: `Item ${i}`,
      color: i % 2 ? '#e0f7fa' : '#fffde7',
    })
  }

  onMounted(() => {
    show.value = true
  })
</script>

<style scoped>
  .test-container {
    padding: 20px;
  }
  .scroll-container {
    height: 500px;
    border: 1px solid #ddd;
    overflow: auto;
  }
  .list-item {
    height: 60px;
    line-height: 60px;
    padding: 0 16px;
    border-bottom: 1px solid #eee;
    box-sizing: border-box;
  }
</style>

Props Configuration

Name	Type	Required	Default	Description
v-model	Boolean	Yes	false	Controls whether virtual scrolling is enabled (must use v-model binding)
ban	Boolean	No	false	Disable virtual scrolling (for small datasets)
itemSize	Number	Required for fixed height	undefined	Item height in fixed-height mode (px)
minItemSize	Number	Required for dynamic height	undefined	Minimum item height in dynamic-height mode (px)
data	Array	Yes	[]	Data array to render
buffer	Array	No	[200, 200]	Buffer zone sizes [top buffer, bottom buffer] (px)
keyField	String	No	'id'	Field name for unique identifier in data items
dataUid	String	No	'data-uid'	DOM attribute name for storing data unique identifier
viewNum	Number	No	1	Minimum number of items visible initially (for estimation)

Slots

default

Main rendering slot for defining each item's content

Slot Parameters

Parameter	Type	Description
item	Object	Current data item
index	Number	Item index in data
dataUid	String	Item unique identifier

Usage Scenarios

1. Fixed Height Mode

When all items have the same height, use fixed height mode for optimal performance:

<async-virtual-scroll v-model="enabled" :data="largeList" :item-size="60">
  <!-- template content -->
</async-virtual-scroll>

2. Dynamic Height Mode

When items have varying heights, use dynamic height mode:

<async-virtual-scroll v-model="enabled" :data="varyingHeightList" :min-item-size="40">
  <!-- template content -->
</async-virtual-scroll>

3. Disable Virtual Scrolling

Disable virtual scrolling for small datasets:

<async-virtual-scroll :data="list" :ban="list.length < 100">
  <!-- template content -->
</async-virtual-scroll>

4. Custom Buffer Zone

Adjust buffer sizes as needed:

<async-virtual-scroll :data="list" :buffer="[150, 300]">
  <!-- template content -->
</async-virtual-scroll>

Important Notes

1. Must bind v-model

2. Dynamic Height Mode Requirements

   • Must provide minItemSize property for initial height estimation
   • Component automatically detects and updates layout when item heights change

3. Performance Optimization Suggestions

   • Prefer itemSize for fixed-height items
   • Set appropriate buffer values to balance performance and UX
   • Avoid complex computations in item templates

4. Data Updates

   • Layout automatically updates when data changes
   • Render area automatically adjusts for significant data changes

Why?

Traditional rendering methods create all DOM elements at once for large datasets, causing:

1. High Memory Usage: Thousands of DOM nodes consume significant memory
2. Reduced Rendering Performance: Browser handles excessive layout and paint operations
3. Interaction Lag: Noticeable stuttering during scrolling and user interactions

Asynchronous Virtual Scrolling solves these issues by:

• 🚀 On-demand Rendering: Only renders elements in viewport
• ⏱ Deferred Calculation: Uses IntersectionObserver for async visibility detection
• 🔄 Smart Buffering: Preloads elements outside viewport for smooth scrolling
• 📊 Height Caching: Records rendered element heights to avoid recalculation

Demo

demo.mp4

License

MIT License