跪拜 Guibai
← All articles
Frontend

vue-virtualize: A Zero-Dependency Vue3 Virtual List That Keeps 100K Rows Smooth

By lcy_24 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Virtualization is the standard fix for long-list jank in admin dashboards, and vue-virtualize packages it into a type-safe, dependency-free component with features like overscan and targeted scrolling. It saves frontend developers from reimplementing a tricky pattern and highlights practical trade-offs like fixed-height limits that cover most real-world lists.

Summary

vue-virtualize is a zero-dependency Vue3 component that decouples DOM count from data size by rendering only the visible range of items plus a buffer. It uses a spacer element to simulate the full scroll height and absolute positioning to offset each item correctly. The component exposes a scrollToIndex method with start, center, and end alignment modes, and it recomputes the viewport dynamically via ResizeObserver to handle container resizing.

The library assumes fixed item heights, which covers most table, log, and stream scenarios but not dynamic-height lists like masonry or rich-text cards. Its documentation warns that using index as the key can corrupt state in interactive items, so a keyField prop lets users switch to a stable identifier. The author also notes that scroll events do not need throttling because the bottleneck is DOM count, not computation, and explains the build setup: vite for JS/CSS and vue-tsc for .d.ts to avoid a declaration-file error.

Takeaways
— The component renders only the items in the visible range plus a buffer, keeping DOM nodes constant regardless of data size.
— A spacer element with height equal to items.length times itemSize makes the scrollbar appear as long as the full list.
— Buffer (overscan) defaults to 6 items above and below the viewport to prevent white flashes during fast scrolling.
— Using index as the key causes state mixing in interactive items; the keyField prop accepts a stable identifier like an id.
— ResizeObserver watches the container and recomputes the viewport height on resize.
— scrollToIndex lets you jump to a specific item with alignment modes start, center, and end.
— The component is fixed-height only, covering 80% of scenarios (tables, logs, equal-height rows) but not dynamic-height lists.
— The scroll handler does a simple assignment and computed recompute; throttling is unnecessary because DOM count is the bottleneck.
— Build uses vite for JS/CSS and vue-tsc separately for .d.ts to avoid the defineProps declaration error.
— The library is available on npm as vue-virtualize.
Conclusions

The fixed-height assumption is a deliberate trade-off that keeps the implementation simple while covering the vast majority of enterprise list scenarios.

Index-based keys are a notorious source of state corruption in virtualized lists, and the keyField prop offers a clean escape hatch without forcing a specific key scheme.

Skipping scroll throttling is a useful reminder that performance bottlenecks in this pattern are DOM-related, not computation-related, and adding throttling can introduce latency.

Concepts & terms
Virtual list (virtualization)
A technique that renders only the items currently visible in the viewport (plus a small buffer) instead of the entire dataset, keeping the number of DOM nodes constant and decoupling performance from data size.
Overscan (buffer)
Extra items rendered outside the visible viewport to prevent white flashes during fast scrolling, typically set to a few rows above and below the current scroll position.
ResizeObserver
A browser API that watches an element's size changes and triggers a callback, used here to recompute the viewport height when the container resizes or layout shifts.
From the discussion
Featured comments
组合搭配函数

Rendering only the visible area is a solid move; with a hundred thousand items the DOM stays constant at a few dozen, the approach is remarkably clean. That pitfall of using index as the key causing row misalignment is pinpointed accurately.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗