DOCSEARCHbyAlgolia
Submit Docs

vue-virtual-scroller

repository·master·Indexed 27 days ago

https://github.com/akryum/vue-virtual-scroller

A high-performance virtual scrolling library for Vue 3 applications designed to handle large datasets by rendering only items visible in the viewport. It provides components like RecycleScroller for fixed-size items and grids, and DynamicScroller for items with unknown row heights. The library also includes headless hooks such as useDynamicScroller and useTableColumnWidths for implementing virtualized semantic tables.

Tokens
36.8K
Snippets
67
Records
153
Agent score
92%

What's inside vue-virtual-scroller

  1. Overview of vue-virtual-scroller components

    master

    The library provides several components for different virtualization scenarios:

    • RecycleScroller: The primary component for lists where item sizes are known or already stored in your data.
    • DynamicScroller: Built on RecycleScroller, this component measures items as they render when sizes are not known in advance.
    • DynamicScrollerItem: A measurement wrapper used inside DynamicScroller.
    • WindowScroller: A version of the API designed for lists that follow the browser window/page scrolling instead of an inner container.

  2. Overview of Vue Virtual Scroller features

    master

    Vue Virtual Scroller is a library designed to render large Vue lists smoothly by only rendering visible items, which keeps DOM work low and maintains responsiveness. It provides several ways to handle virtualization:

    • RecycleScroller: The default component for lists where item sizes are known or data-driven sizes are available upfront.
    • DynamicScroller: Used when item height or width is unknown ahead of time; it measures rows as they render.
    • Headless APIs: Allows you to use the underlying virtualization engine with your own custom markup, semantics, and design system components.

  3. Reference map for Vue Virtual Scroller components and hooks

    master

    This project provides several virtualization strategies via components and headless hooks. Use the following components and hooks depending on your use case:

    Components

    • RecycleScroller: For fixed-size or pre-sized items. Supports grid mode and cache restoration.
    • DynamicScroller: For items with unknown sizes that need to be measured after rendering.
    • DynamicScrollerItem: A wrapper used inside DynamicScroller for per-item measurement.
    • WindowScroller: For lists that are driven by the browser window's scroll position.

    Headless Hooks

    • useRecycleScroller: For custom markup with known or pre-sized items.
    • useDynamicScroller: For dynamic measurement paths (used with vDynamicScrollerItem).
    • useWindowScroller: For window-scrolling virtualization.
    • useTableColumnWidths: A helper to lock semantic table column widths after measurement.

  4. Use RecycleScroller for fixed or pre-sized virtualization

    master

    The RecycleScroller is the primary component for virtualization when item dimensions are known or predictable. It supports fixed-size rows/columns, grids, and native-flow rendering via flowMode.

    When to use

    • Item height or width is fixed.
    • Each item exposes a numeric size field.
    • Item size can be derived via an itemSize(item, index) resolver function.
    • You need grid rendering with fixed item dimensions.
    • You prefer a component API over a headless render loop.

  5. Use DynamicScroller for items with unknown row heights

    master

    Use the DynamicScroller component when the height of your list items cannot be determined until they are actually rendered. This component works in conjunction with DynamicScrollerItem to manage variable-sized rows.

    Key props:

    • :items: The array of data to be virtualized.
    • :min-item-size: An estimate of the minimum height of an item. Providing an accurate estimate helps improve the initial render performance and scroll stability.
    <script setup lang="ts">
import { ref } from 'vue'
import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'

const items = ref([{ id: 1, text: 'Hello' }, { id: 2, text: 'World' }])
const minItemSize = ref(50)
</script>

<template>
  <DynamicScroller
    :items="items"
    :min-item-size="minItemSize"
  >
    <template #default="{ item, index, active }">
      <DynamicScrollerItem
        :item="item"
        :active="active"
      >
        <div>{{ item.text }}</div>
      </DynamicScrollerItem>
    </template>
  </DynamicScroller>
</template>

  6. Disable the scroller using the `enabled` option

    master

    You can put useRecycleScroller into a passive mode by setting enabled: false. In this mode:

    • No scroll/resize listeners are attached.
    • No watchers, RAFs, or timers are scheduled.
    • pool and visiblePool stay empty.
    • totalSize, startSpacerSize, and endSpacerSize stay at 0.
    • ready stays false.

    This is useful for design-system components that always invoke the hook but only opt into virtualization conditionally.

    Note: All methods (like scrollToItem) become no-ops when disabled and are safe to call.

    const isVirtualized = computed(() => props.virtualize)

const scroller = useRecycleScroller(() => ({
  items: rows.value,
  keyField: 'id',
  itemSize: null,
  minItemSize: 40,
  // ...
  enabled: isVirtualized.value,
}), scrollerEl)

  8. Install and setup vue-virtual-scroller

    master

    To use vue-virtual-scroller in a Vue 3 project, ensure you are using Vue 3.3+ and an ESM-aware toolchain (like Vite, Nuxt, Rollup, or webpack 5).

    1. Install the package via pnpm:
    pnpm add vue-virtual-scroller
    1. Import the required CSS:
    import 'vue-virtual-scroller/index.css'
    1. Register the library. You can install all bundled components globally or register specific components as needed.
    // Option 1: Install all bundled components
import { createApp } from 'vue'
import VueVirtualScroller from 'vue-virtual-scroller'

const app = createApp(App)
app.use(VueVirtualScroller)

// Option 2: Register only what you need
import { RecycleScroller, WindowScroller } from 'vue-virtual-scroller'

app.component('RecycleScroller', RecycleScroller)
app.component('WindowScroller', WindowScroller)

  10. Use TypeScript generics with RecycleScroller

    master

    With Vue 3.3+, RecycleScroller automatically infers the item type from the items prop, making the default slot type-aware in <script setup lang="ts"> environments.

    <script setup lang="ts">
import { ref } from 'vue'

interface Message {
  id: string
  text: string
  size: number
}

const messages = ref<Message[]>([])
</script>

<template>
  <RecycleScroller :items="messages" :item-size="32">
    <template #default="{ item }">
      {{ item.text.toUpperCase() }}
    </template>
  </RecycleScroller>
</template>