1---
2category: Component
3---
4 
5# useVirtualList
6 
7::: warning
8Consider using [`@tanstack/vue-virtual`](https://tanstack.com/virtual/v3/docs/framework/vue/vue-virtual) instead, if you are looking for more features.
9:::
10 
11Create virtual lists with ease. Virtual lists (sometimes called [_virtual scrollers_](https://vue-virtual-scroller-demo.netlify.app/)) 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.
12 
13## Usage
14 
15### Simple list
16 
17```ts
18import { useVirtualList } from '@vueuse/core'
19 
20const { list, containerProps, wrapperProps } = useVirtualList(
21  Array.from(Array.from({ length: 99999 }).keys()),
22  {
23    // Keep `itemHeight` in sync with the item's row.
24    itemHeight: 22,
25  },
26)
27```
28 
29### Config
30 
31| State      | Type     | Description                                                                                     |
32| ---------- | -------- | ----------------------------------------------------------------------------------------------- |
33| itemHeight | `number` | ensure that the total height of the `wrapper` element is calculated correctly.\*                |
34| itemWidth  | `number` | ensure that the total width of the `wrapper` element is calculated correctly.\*                 |
35| overscan   | `number` | number of pre-rendered DOM nodes. Prevents whitespace between items if you scroll very quickly. |
36 
37\* 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.
38 
39### Reactive list
40 
41```ts
42import { useToggle, useVirtualList } from '@vueuse/core'
43import { computed } from 'vue'
44 
45const [isEven, toggle] = useToggle()
46const allItems = Array.from(Array.from({ length: 99999 }).keys())
47const filteredList = computed(() => allItems.filter(i => isEven.value ? i % 2 === 0 : i % 2 === 1))
48 
49const { list, containerProps, wrapperProps } = useVirtualList(
50  filteredList,
51  {
52    itemHeight: 22,
53  },
54)
55```
56 
57```vue
58<template>
59  <p>Showing {{ isEven ? 'even' : 'odd' }} items</p>
60  <button @click="toggle">
61    Toggle Even/Odd
62  </button>
63  <div v-bind="containerProps" style="height: 300px">
64    <div v-bind="wrapperProps">
65      <div v-for="item in list" :key="item.index" style="height: 22px">
66        Row: {{ item.data }}
67      </div>
68    </div>
69  </div>
70</template>
71```
72 
73### Horizontal list
74 
75```ts
76import { useVirtualList } from '@vueuse/core'
77 
78const allItems = Array.from(Array.from({ length: 99999 }).keys())
79 
80const { list, containerProps, wrapperProps } = useVirtualList(
81  allItems,
82  {
83    itemWidth: 200,
84  },
85)
86```
87 
88```vue
89<template>
90  <div v-bind="containerProps" style="height: 300px">
91    <div v-bind="wrapperProps">
92      <div v-for="item in list" :key="item.index" style="width: 200px">
93        Row: {{ item.data }}
94      </div>
95    </div>
96  </div>
97</template>
98```
99 
100## Component Usage
101 
102```vue
103<template>
104  <UseVirtualList :list="list" :options="options" height="300px">
105    <template #default="props">
106      <!-- you can get current item of list here -->
107      <div style="height: 22px">
108        Row {{ props.index }} {{ props.data }}
109      </div>
110    </template>
111  </UseVirtualList>
112</template>
113```
114 
115To scroll to a specific element, the component exposes `scrollTo(index: number) => void`.
116 
117## Type Declarations
118 
119```ts
120type UseVirtualListItemSize = number | ((index: number) => number)
121export interface UseHorizontalVirtualListOptions extends UseVirtualListOptionsBase {
122  /**
123   * item width, accept a pixel value or a function that returns the width
124   *
125   * @default 0
126   */
127  itemWidth: UseVirtualListItemSize
128}
129export interface UseVerticalVirtualListOptions extends UseVirtualListOptionsBase {
130  /**
131   * item height, accept a pixel value or a function that returns the height
132   *
133   * @default 0
134   */
135  itemHeight: UseVirtualListItemSize
136}
137export interface UseVirtualListOptionsBase {
138  /**
139   * the extra buffer items outside of the view area
140   *
141   * @default 5
142   */
143  overscan?: number
144}
145export type UseVirtualListOptions =
146  | UseHorizontalVirtualListOptions
147  | UseVerticalVirtualListOptions
148export interface UseVirtualListItem<T> {
149  data: T
150  index: number
151}
152export interface UseVirtualListReturn<T> {
153  list: Ref<UseVirtualListItem<T>[]>
154  scrollTo: (index: number) => void
155  containerProps: {
156    ref: Ref<HTMLElement | null>
157    onScroll: () => void
158    style: StyleValue
159  }
160  wrapperProps: ComputedRef<{
161    style:
162      | {
163          width: string
164          height: string
165          marginTop: string
166        }
167      | {
168          width: string
169          height: string
170          marginLeft: string
171          display: string
172        }
173  }>
174}
175/**
176 * Please consider using [`vue-virtual-scroller`](https://github.com/Akryum/vue-virtual-scroller) if you are looking for more features.
177 */
178export declare function useVirtualList<T = any>(
179  list: MaybeRef<readonly T[]>,
180  options: UseVirtualListOptions,
181): UseVirtualListReturn<T>
182```
183