useVirtualList | VueUse

useVirtualList
​
Category
Component
Export Size
1.8 kB
Last Changed
2 months ago

WARNING

Consider using vue-virtual-scroller instead, if you are looking for more features.

Create virtual lists with ease. Virtual lists (sometimes called virtual scrollers) allow you to render a large number of items performantly. They only render the minimum number of DOM nodes necessary to show the items within the container element by using the wrapper element to emulate the container element's full height.

Demo
​

source

Jump to index
Go
Filter list by size
Row 0
(small)
Row 1
(large)
Row 2
(small)
Row 3
(large)
Row 4
(small)
Row 5
(large)
Row 6
(small)
Row 7
(large)
Row 8
(small)
Row 9
(large)
Row 10
(small)
Row 11
(large)
Row 12
(small)
Row 13
(large)
Row 14
(small)
Usage
​
Simple list
​
typescript
import { useVirtualList } from '@vueuse/core'

const { list, containerProps, wrapperProps } = useVirtualList(
  Array.from(Array(99999).keys()),
  {
    // Keep `itemHeight` in sync with the item's row.
    itemHeight: 22,
  },
)
Config
​
State	Type	Description
itemHeight	number	ensure that the total height of the wrapper element is calculated correctly.*
itemWidth	number	ensure that the total width of the wrapper element is calculated correctly.*
overscan	number	number of pre-rendered DOM nodes. Prevents whitespace between items if you scroll very quickly.

* The itemHeight or itemWidth must be kept in sync with the height of each row rendered. If you are seeing extra whitespace or jitter when scrolling to the bottom of the list, ensure the itemHeight or itemWidth is the same height as the row.

Reactive list
​
typescript
import { useVirtualList, useToggle } from '@vueuse/core'
import { computed } from 'vue'

const [isEven, toggle] = useToggle()
const allItems = Array.from(Array(99999).keys())
const filteredList = computed(() => allItems.filter(i => isEven.value ? i % 2 === 0 : i % 2 === 1))

const { list, containerProps, wrapperProps } = useVirtualList(
  filteredList,
  {
    itemHeight: 22,
  },
)
html
<template>
  <p>Showing {{ isEven ? 'even' : 'odd' }} items</p>
  <button @click="toggle">Toggle Even/Odd</button>
  <div v-bind="containerProps" style="height: 300px">
    <div v-bind="wrapperProps">
      <div v-for="item in list" :key="item.index" style="height: 22px">
        Row: {{ item.data }}
      </div>
    </div>
  </div>
</template>
Horizontal list
​
typescript
import { useVirtualList } from '@vueuse/core'

const allItems = Array.from(Array(99999).keys())

const { list, containerProps, wrapperProps } = useVirtualList(
  allItems,
  {
    itemWidth: 200,
  },
)
html
<template>
  <div v-bind="containerProps" style="height: 300px">
    <div v-bind="wrapperProps">
      <div v-for="item in list" :key="item.index" style="width: 200px">
        Row: {{ item.data }}
      </div>
    </div>
  </div>
</template>
Component Usage
​

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

html
<UseVirtualList :list="list" :options="options" height="300px">
  <template #="props">
    <!-- you can get current item of list here -->
    <div style="height: 22px">Row {{ props.data }}</div>
  </template>
</UseVirtualList>

To scroll to a specific element, the component exposes scrollTo(index: number) => void.

Source
​

Source • Demo • Docs

Contributors
​
Anthony Fu
wheat
karukenert
Ruben Laguna
Minh Anh Nguyen
vaakian X
Nikola Begedin
Eric Skaliks
vaakian X
Maxim Brynze
Jelf
Jessica Sachs
Che Guevara
Changelog
​
v10.6.1 on 11/13/2023
3d6b9 - fix: .style can be undefined
v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
25f6e - fix: List sometimes missing elements (#2477)
v9.10.0 on 1/3/2023
9f495 - feat(useVirutalList): expose scrollTo in component (#2397)
v9.4.0 on 10/25/2022
bceda - feat: horizontal list (#2310)