1---
2title: Virtualize Large Lists to Avoid DOM Overload
3impact: HIGH
4impactDescription: Rendering thousands of list items creates excessive DOM nodes, causing slow renders and high memory usage
5type: efficiency
6tags: [vue3, performance, virtual-list, large-data, dom, optimization]
7---
8 
9# Virtualize Large Lists to Avoid DOM Overload
10 
11**Impact: HIGH** - Rendering all items in a large list (hundreds or thousands) creates massive amounts of DOM nodes. Each node consumes memory, slows down initial render, and makes updates expensive. List virtualization only renders visible items, dramatically improving performance.
12 
13Use a virtualization library when dealing with lists that could exceed 50-100 items, especially if items have complex content.
14 
15## Task List
16 
17- Identify lists that render more than 50-100 items
18- Install a virtualization library (vue-virtual-scroller, @tanstack/vue-virtual)
19- Replace standard `v-for` with virtualized component
20- Ensure list items have consistent or estimable heights
21- Test with realistic data volumes during development
22 
23## Recommended Libraries
24 
25| Library | Best For | Notes |
26|---------|----------|-------|
27| `vue-virtual-scroller` | General use, easy setup | Most popular, good defaults |
28| `@tanstack/vue-virtual` | Complex layouts, headless | Framework-agnostic, flexible |
29| `vue-virtual-scroll-grid` | Grid layouts | 2D virtualization |
30| `vueuc/VVirtualList` | Naive UI projects | Part of Naive UI ecosystem |
31 
32**BAD:**
33```vue
34<template>
35  <!-- BAD: Renders ALL 10,000 items immediately -->
36  <div class="user-list">
37    <UserCard
38      v-for="user in users"
39      :key="user.id"
40      :user="user"
41    />
42  </div>
43</template>
44 
45<script setup>
46import { ref, onMounted } from 'vue'
47import UserCard from './UserCard.vue'
48 
49const users = ref([])
50 
51onMounted(async () => {
52  // 10,000 DOM nodes created, browser struggles
53  users.value = await fetchAllUsers()
54})
55</script>
56```
57 
58**GOOD:**
59```vue
60<template>
61  <!-- GOOD: Only renders ~20 visible items at a time -->
62  <RecycleScroller
63    class="user-list"
64    :items="users"
65    :item-size="80"
66    key-field="id"
67    v-slot="{ item }"
68  >
69    <UserCard :user="item" />
70  </RecycleScroller>
71</template>
72 
73<script setup>
74import { ref, onMounted } from 'vue'
75import { RecycleScroller } from 'vue-virtual-scroller'
76import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'
77import UserCard from './UserCard.vue'
78 
79const users = ref([])
80 
81onMounted(async () => {
82  // 10,000 items in memory, but only ~20 DOM nodes
83  users.value = await fetchAllUsers()
84})
85</script>
86 
87<style scoped>
88.user-list {
89  height: 600px; /* Container must have fixed height */
90}
91</style>
92```
93 
94## Using @tanstack/vue-virtual
95 
96```vue
97<template>
98  <div ref="parentRef" class="list-container">
99    <div
100      :style="{
101        height: `${rowVirtualizer.getTotalSize()}px`,
102        position: 'relative'
103      }"
104    >
105      <div
106        v-for="virtualRow in rowVirtualizer.getVirtualItems()"
107        :key="virtualRow.key"
108        :style="{
109          position: 'absolute',
110          top: 0,
111          left: 0,
112          width: '100%',
113          height: `${virtualRow.size}px`,
114          transform: `translateY(${virtualRow.start}px)`
115        }"
116      >
117        <UserCard :user="users[virtualRow.index]" />
118      </div>
119    </div>
120  </div>
121</template>
122 
123<script setup>
124import { ref } from 'vue'
125import { useVirtualizer } from '@tanstack/vue-virtual'
126 
127const users = ref([/* 10,000 users */])
128const parentRef = ref(null)
129 
130const rowVirtualizer = useVirtualizer({
131  count: users.value.length,
132  getScrollElement: () => parentRef.value,
133  estimateSize: () => 80,  // Estimated row height
134  overscan: 5  // Render 5 extra items above/below viewport
135})
136</script>
137 
138<style scoped>
139.list-container {
140  height: 600px;
141  overflow: auto;
142}
143</style>
144```
145 
146## Dynamic Heights with vue-virtual-scroller
147 
148```vue
149<template>
150  <!-- For variable height items, use DynamicScroller -->
151  <DynamicScroller
152    :items="messages"
153    :min-item-size="54"
154    key-field="id"
155  >
156    <template #default="{ item, index, active }">
157      <DynamicScrollerItem
158        :item="item"
159        :active="active"
160        :data-index="index"
161      >
162        <ChatMessage :message="item" />
163      </DynamicScrollerItem>
164    </template>
165  </DynamicScroller>
166</template>
167 
168<script setup>
169import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
170</script>
171```
172 
173## Performance Comparison
174 
175| Approach | 100 Items | 1,000 Items | 10,000 Items |
176|----------|-----------|-------------|--------------|
177| Regular v-for | ~100 DOM nodes | ~1,000 DOM nodes | ~10,000 DOM nodes |
178| Virtualized | ~20 DOM nodes | ~20 DOM nodes | ~20 DOM nodes |
179| Initial render | Fast | Slow | Very slow / crashes |
180| Virtualized render | Fast | Fast | Fast |
181 
182## When NOT to Virtualize
183 
184- Lists under 50 items with simple content
185- Lists where all items must be accessible to screen readers simultaneously
186- Print layouts where all content must render
187- SEO-critical content that must be in initial HTML
188