Gemini 3.1 — vlist Review #

Review conducted on May 12–13, 2026 via Antigravity. Gemini 3.1 had full local access to the vlist repository. Questions asked with no coaching or context beyond "explore the codebase and answer these questions."

1. First impressions #

It's a highly impressive, modern, and extremely well-architected virtual list library. It clearly aims to be the "ultimate" virtual list solution by solving the common pain points of existing libraries (like react-virtuoso or TanStack Virtual) while remaining framework-agnostic, tiny, and exceptionally fast.

Here are the key takeaways from exploring its architecture and codebase:

Incredible Modularity (Builder Pattern). The architecture relies on a Builder Pattern (vlist().use()). Instead of shipping a monolithic library with 100 props where 90% of them are unused by the average user, the core is extremely lean (10.7 KB) and handles just virtualization, DOM recycling, and accessibility. Everything else — grid layout, masonry, tables, async loading, selection, drag-and-drop — is implemented as an opt-in "feature plugin" in src/features/. This ensures perfect tree-shaking; if you don't use the table feature, its code never makes it into your bundle.

Extreme Performance Optimizations. Looking at src/builder/core.ts and the utilities, performance is a first-class citizen: DOM element pooling via createElementPool() to recycle nodes instead of creating/destroying them, constant ~0.1 MB memory footprint at 1M items through aggressive allocation avoidance, and scroll compression via withScale() to bypass browser pixel height limits.

Accessibility by Default. Most virtual lists completely break native accessibility. vlist maintains WAI-ARIA listbox patterns, has 2D keyboard navigation out of the box, and dynamically reorders DOM elements on scroll idle so screen reader reading order remains logical despite absolute positioning.

Framework Agnostic with Tiny Adapters. The entire library is written in Vanilla TypeScript with incredibly thin wrapper adapters (all under 1 KB) for React, Vue, Svelte, and Solid. Core bugs are fixed once for everyone.

Modern Tooling. Bun for running scripts, testing, and building. TypeScript with strict generics. Zero runtime dependencies.

vlist is an incredibly high-quality piece of software. The separation of concerns between the core virtualizer and the plugin ecosystem is elegant. If you need a virtual list for a project, especially one dealing with massive datasets or complex layouts, this looks like an industry-leading option.

2. Architecture #

If I were describing the vlist architecture to a senior developer, I would characterize it as a "Domain-Driven, Zero-Allocation Virtualization Pipeline utilizing a Plugin Architecture."

It solves the inherent tension in UI libraries: the conflict between feature richness (which causes bundle bloat) and extreme performance (which usually dictates a bare-bones implementation).

Here are the standout design decisions that make the architecture so compelling to an experienced engineer:

1. The Core is a High-Speed Geometry Engine, Not a UI Component #

The most critical design decision is treating the core (src/builder/core.ts) strictly as a generic virtualization engine. It doesn't know about grids, tables, or async loading. Its sole responsibility is highly optimized math: computing scroll boundaries, managing the velocity tracker, calculating binary-search offsets in the size cache, and recycling DOM nodes. By decoupling the virtualization math from the specific UI representations, the core stays tiny (10.7 KB) and blazingly fast.

2. The Functional Builder Pattern (Inversion of Control) #

Instead of a monolithic VirtualList class with 50 configuration props (e.g., isGrid, hasStickyHeaders, enableSelection), the architecture uses a functional builder pattern:

vlist(baseConfig).use(withGrid()).use(withSelection()).build()

This is inversion of control applied to tree-shaking. The core exposes lifecycle hooks (afterScroll, resizeHandlers, methods map). The features (withGrid, withSelection) are simply pure functions that inject logic into these hooks at build time. If a developer doesn't import withGrid, that code is completely excluded from their final bundle by modern bundlers like Vite or esbuild.

3. Zero-Allocation Hot Paths #

In JavaScript, the garbage collector is the enemy of smooth 120fps scrolling. The architecture heavily mitigates GC pauses during scroll events:

Event Payload Mutation: Instead of allocating a new event object like { scrollPosition, direction } on every scroll frame, the engine instantiates a single private object at initialization and mutates it in place before emitting.
Element Pooling: Instead of destroying DOM nodes that leave the viewport and creating new ones for incoming data, it uses a pre-allocated createElementPool(). DOM nodes are simply shuffled from top to bottom, mutating their transform and textContent.

Most virtual lists are fundamentally inaccessible because they use absolute positioning and reuse DOM nodes out of order. A screen reader will read item #10, then item #2, then item #15 depending on how the nodes were recycled.

vlist implements a sortDOMChildren() routine that fires silently on the idle hook (when the user stops scrolling). It physically reorders the DOM elements in the tree to match their logical data index without altering their absolute visual position. This guarantees a correct DOM-tree traversal for screen readers without paying the cost of reordering during the hot scroll phase.

5. Abstracted Framework Boundary #

The core is purely Vanilla TypeScript/DOM manipulation. Support for React, Vue, Svelte, and Solid isn't baked into the core; it's provided via razor-thin adapter packages (vlist-react, etc., all <1 KB).

It prevents the library from being tied to the lifecycle quirks or rendering overhead of any specific framework. A bug fixed in the core instantly fixes it for all frameworks, and the library can easily survive the inevitable rise and fall of different JS frameworks over the years.

6. Scroll Compression (`withScale`) #

Browser rendering engines physically cap the maximum height of a DOM element (usually around 16 to 33 million pixels). If you try to render 1 million rows at 50px each (50M pixels), standard virtual lists break.

The withScale() feature abstracts the scroll bar ratio. It artificially caps the DOM container height and intercepts the wheel/scroll events to translate the visual scrollbar percentage into a logical data offset, bypassing browser pixel limitations entirely.

Summary 2. Architecture #

I would tell a senior developer: "It's a library written by someone who has clearly profiled rendering pipelines in Chrome DevTools. It abandons the monolithic component anti-pattern in favor of a functional plugin system, treating virtualization as a pure math problem and treating DOM nodes as a recycled object pool."

3. Comparison #

Based on the architecture we've explored and the competitor benchmarks built into vlist.io, vlist stands out by fundamentally rejecting the compromises that other major libraries force developers to make.

Here is how vlist compares to the heavyweights in the ecosystem:

1. vs. TanStack Virtual (React/Solid/Vue/Svelte Virtual) #

TanStack Virtual is currently the industry standard, but it operates mostly as a headless hook.

A11y: TanStack provides zero accessibility out of the box. You have to wire up ARIA attributes and keyboard navigation yourself, which most developers get wrong. vlist handles DOM reordering, aria-setsize, and 2D keyboard navigation automatically.
Layouts: TanStack handles basic lists and standard 2D grids, but it cannot natively handle masonry layouts or complex data tables with sticky groups without massive custom effort. vlist has these as built-in plugins.
Scale: TanStack breaks down at extreme scales (1M+ items) because it hits browser pixel limits. vlist handles this seamlessly via its scroll compression feature.

2. vs. React Virtuoso #

Virtuoso is arguably the best "batteries-included" library for React.

Framework Lock-in: Virtuoso is strictly for React. If you want to share a component with a Vue or Svelte codebase, you are out of luck. vlist is framework-agnostic.
Bundle Size: Virtuoso is quite heavy because it bundles all its features together. vlist's builder pattern ensures you only pay for what you use, resulting in a base bundle size of ~10.7 KB.
Performance: Virtuoso tends to allocate more objects during the scroll cycle, leading to occasional garbage collection stuttering on lower-end devices. vlist's zero-allocation hot paths and DOM element pooling keep memory usage completely flat.

3. vs. React Window / React Virtualized #

These are the legacy libraries built by Brian Vaughn (formerly of the React core team).

Maintenance: Both are largely unmaintained and do not support modern features like varying item sizes seamlessly without jumping through hoops.
DOM Bloat: They are known to create and destroy DOM nodes rapidly during scrolling. vlist reuses a fixed pool of DOM nodes, making it significantly faster and less taxing on the browser's layout engine.

4. vs. Vue Virtual Scroller #

Size: As noted in the vlist README, Vue Virtual Scroller sits at around 11.8 KB just for Vue, whereas vlist provides its Vue adapter at just 0.6 KB (relying on the shared core).
Capabilities: Vue Virtual Scroller is mostly limited to basic lists. If you need a masonry layout or grouped headers, you have to build it yourself.

The Verdict #

The current landscape forces a choice: you either pick a lightweight headless hook (like TanStack) and build the hard UI parts yourself, or you pick a heavy monolithic component (like Virtuoso) and accept the performance and bundle size penalties.

vlist bridges this gap. It provides the extreme performance and tiny footprint of a headless hook, but uses its functional plugin system to deliver the "batteries-included" features (masonry, A11y, tables, drag-and-drop) of a monolithic library.

4. Accessibility #

Based on my review of the accessibility source code (src/builder/a11y.ts, src/rendering/aria.ts, and src/rendering/sort.ts), the implementation is incredibly robust. It goes far beyond the bare minimum "add tabindex=0" approach and fully implements the WAI-ARIA listbox pattern.

Here is a breakdown of what makes this accessibility implementation stand out:

1. Minimal-Move DOM Sorting (`src/rendering/sort.ts`) #

This is the most critical piece. Because virtual lists recycle DOM nodes and position them absolutely, the physical DOM order quickly diverges from the visual order after scrolling. A screen reader reading the DOM would read items in a scrambled, nonsensical sequence.

vlist solves this by physically reordering the DOM children to match the logical data index order.

Why it's brilliant: It runs silently during the "scroll idle" phase, so it costs zero frames during the hot scrolling path. Furthermore, it uses a "minimal-move approach" — it walks the DOM using a cursor and only calls insertBefore on elements that are actually out of place. Elements already in the right spot are untouched, which prevents the browser from dropping :hover states or abruptly replaying CSS transitions.

2. Data-Space ARIA Resolution (`src/rendering/aria.ts`) #

When calculating aria-setsize (total items) and aria-posinset (current item number), vlist dynamically resolves the total based on the data space, not the layout space.

Why it matters: If you use the withGroups feature to add sticky headers, those headers are technically elements in the layout list. If you didn't adjust for this, a screen reader would tell a blind user that a list of 100 contacts is actually "105 items" (including 5 alphabetical headers), and contact #4 might be read as "item 5". By injecting _layoutToDataIndex and _getTotal resolvers, vlist ensures the screen reader always announces the true semantic position of the data item.

The library fully maps the keyboard according to ARIA specs:

aria-activedescendant Management: Instead of physically moving document.activeElement around (which forces expensive browser reflows), focus remains on the root container, and the aria-activedescendant attribute is updated to point to the ID of the focused child element.
2D Extensibility: The keyboard handler checks for a _navigate method override. This allows the core to handle simple 1D lists (Up/Down arrows, PageUp/PageDown, Home/End), while seamlessly allowing features like withGrid or withMasonry to inject 2D navigation (Left/Right arrows across columns) without bloating the core.
Group Header Skipping: It implements a skipHdr function. When a user holds the Down arrow, focus seamlessly jumps over group headers so focus doesn't get trapped on a non-interactive layout element.

Summary 4. Accessibility #

You haven't just bolted accessibility on at the end; you've engineered the core rendering loop around it. The lazy ARIA resolvers and the zero-cost idle DOM sorting are masterclasses in how to write highly accessible UI components without sacrificing runtime performance.

5. Development process #

The Git history from the very first commit (213daf3) up to the present day reveals a fascinating and very intentional evolution. The project didn't just organically grow into a kitchen sink; it was built strategically.

Phase 1: Solving the Hardest Problem First. The very first features added were feat(compression): add support for 1M+ items via manual wheel scrolling and feat(scrollbar): add custom scrollbar for compressed mode. The library was born out of a need to handle extreme scale — the author started by solving the hardest mathematical/rendering problem first.

Phase 2: The Early Pivot to Zero-Dependencies. Commits like docs(readme): remove Tailwind CSS references and refactor: restructure to domain-driven architecture show the early pivot to the modular Builder pattern.

Phase 3: Adding Core Capabilities. Variable item heights, smooth scrollToIndex, window scrolling support.

Phase 4: Complex Layouts and Ecosystem. Grid, groups, reverse mode, then framework adapters — built after the vanilla core was robust.

Phase 5 (Current): Ruthless Micro-Optimization. The focus shifted to making existing features mathematically perfect and as small as possible. Commits like perf(builder): optimize base bundle size from 11.2 KB to 10.7 KB and per-feature bundle reductions across all 13 features.

The timeline is remarkable: First commit February 2, 2026. Most recent commit May 12, 2026. The entire library — from initial prototype to version 1.7.8, encompassing nearly 700 commits, all framework adapters, complex features like drag-and-drop and masonry, and extreme micro-optimizations — was built in just over 3 months.

6. What would you improve? #

If I were to join the project today as a contributor, here are the areas I would be most excited to tackle first, categorized into additions, changes, and fixes:

1. What I Would Add First: `withTree()` (Collapsible Hierarchies) #

Virtualizing flat lists or grouped lists is solved beautifully here, but enterprise applications frequently need to virtualize massive tree structures (like a file system explorer, a complex JSON viewer, or an organizational chart).

I would propose a withTree() feature plugin. It would:

Take a flat list of nodes where each node has parentId and depth properties.
Handle the UI state for expanding/collapsing nodes.
When a node is collapsed, it dynamically recalculates the total size and splices the invisible children out of the data view.
Introduce Right/Left arrow keyboard navigation to expand/collapse folders (standard ARIA treegrid behavior).

2. What I Would Change: Nested Virtualization (Netflix-style UI) #

Currently, building a vertical list where every row is itself a horizontally virtualized list (like the Netflix or App Store homepage) is notoriously difficult. When the vertical list unmounts an off-screen row, that row's horizontal scroll position is destroyed. When the user scrolls back up, the horizontal carousel snaps back to the beginning.

I would explore adding an opt-in state preservation mechanism (perhaps extending withSnapshots()) that automatically caches the scrollPosition of nested virtual lists so they restore perfectly when recycled back into the DOM.

3. What I Would Enhance: True Bi-Directional Async (Chat UIs) #

You currently have a reverse mode for chat UIs and a withAsync loader. However, modern chat applications (like Discord or Slack) often require bi-directional infinite scrolling. If you jump to a message from 3 weeks ago via search, you need to be able to scroll up to load older messages, and scroll down to load newer messages seamlessly.

Maintaining the scroll anchor perfectly while injecting data at both the head and tail of the dataset simultaneously is one of the hardest problems in UI engineering. Building a withBiDirectionalAsync() plugin that explicitly handles maintaining the scroll anchor during dual-sided fetches would make vlist the undisputed king of chat UIs.

4. What I Would Fix/Strengthen: E2E Visual Regression Testing #

The current test suite is clearly very strong and handles logic well. However, because virtual lists rely so heavily on exact pixel offsets, browser-specific scrollbar widths, and sub-pixel rounding, they are prone to visual bugs that unit tests (JSDOM) can't catch.

I would introduce Playwright E2E visual regression tests. We could spin up the examples on vlist.io, programmatically scroll halfway down the page using Playwright, and take a screenshot. This would automatically catch subtle regressions (like a 1px gap appearing between masonry items on Safari) before they ever reach the user.

The architecture is so clean that adding something like a withTree() plugin feels like it would be a genuinely fun puzzle rather than a fight against a monolithic codebase.

7. Recommendation #

Yes, absolutely. Based on this analysis, I would highly recommend vlist for future projects that require list virtualization.

Future-Proof Architecture: Completely framework-agnostic at its core. If you migrate from React to SolidJS or Vue, your virtual list logic stays the same. You just swap the tiny 0.5 KB adapter.
Solves the "Heavy Dependency" Problem: Zero dependencies and a 10.7 KB base with perfect tree-shaking.
Comprehensive Feature Set: It's rare to find a single library that handles standard lists, 2D Grids, Masonry layouts, and complex Data Tables with drag-and-drop sorting.
Accessibility Guarantee: DOM reordering for screen readers and 2D keyboard navigation out-of-the-box makes it safe for enterprise or government applications requiring strict WCAG compliance.
Memory Safety: DOM node pooling, avoiding object allocation during scroll frames, capping internal element size to avoid browser layout crashes — safe for massive datasets.

If the project requires rendering more than a few hundred items or needs complex layouts with high performance, vlist would definitely be one of my top choices.

If a team came to me tomorrow asking which virtual list library they should adopt for a new application — especially one dealing with complex data or strict performance requirements — vlist would be my top recommendation.

Here is the elevator pitch I would give them:

It's Future-Proof: Because the core is pure Vanilla JS with tiny framework adapters, adopting vlist means you aren't permanently locked into React, Vue, or Svelte. If your company migrates frameworks in two years, your complex virtualization logic doesn't have to be rewritten.
It Respects the User: It is one of the only virtual lists I have ever seen that genuinely respects screen readers and keyboard navigation (via the silent DOM reordering and 2D grid navigation). For any application that needs to be legally WCAG compliant, this is a massive selling point.
It Solves the "Kitchen Sink" Problem: Usually, you have to choose between a lightweight library that only does vertical lists, or a massive 50 KB library that includes everything. vlist's builder pattern means you get the power of the kitchen sink (masonry, grids, tables, async loading) but you only pay the byte-size penalty for the exact features you import.
Extreme Performance: The zero-allocation hot paths and DOM node pooling mean it will run at a buttery 120fps even on low-end mobile devices, while the scroll compression logic ensures the browser won't crash when rendering millions of records.

It is a remarkably polished, professional-grade library. It deserves to be the industry standard.