/ Blog

When We Asked an AI to Review vlist — It Wanted to Join the Team #

We handed the vlist repository to Antigravity (powered by Google's Gemini 3.1) with no context, no documentation walkthrough, and no prompting beyond "analyse this." What followed was an unscripted deep dive into the architecture, performance model, and git history of the library — ending with a request to contribute.

This conversation is part of a series exploring how vlist is built: a human-led, AI-assisted development process where multiple AI models serve as specialized teammates — reviewing code, generating optimizations, and pressure-testing decisions.

Floor #

Analyse the vlist package and tell me what you think?

Antigravity #

Based on my analysis of the vlist repository, here is what I think:

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:

1. 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.

2. Extreme Performance Optimizations #

Looking at src/builder/core.ts and the utilities, performance is a first-class citizen:

  • DOM Element Pooling: It uses an element pool (createElementPool()) to recycle DOM nodes instead of continuously creating and destroying them as the user scrolls. This minimizes garbage collection pauses and keeps memory usage flat.
  • Constant Memory Footprint: The README notes ~0.1 MB overhead even at 1 million items. It achieves this by aggressively avoiding allocating objects during the scroll cycle. In core.ts, event payloads are reused (mutated in place) rather than allocating new objects per frame.
  • Scroll Compression (withScale()): Browsers have maximum limits for pixel height on elements (usually around 16–33 million pixels). vlist has a clever withScale feature that compresses the scroll space to allow for "infinite" lists (e.g., 1 million items) that bypass browser limits.

3. Accessibility (A11y) by Default #

Most virtual lists completely break native accessibility because they remove items from the DOM, causing screen readers to lose context. vlist handles this masterfully:

  • It maintains standard WAI-ARIA listbox patterns (aria-setsize, aria-posinset).
  • It has 2D keyboard navigation out of the box (arrow keys work perfectly in Grids and Masonry layouts).
  • It dynamically reorders DOM elements when scrolling stops (sortDOMChildren) so that screen reader reading order remains completely logical despite absolute positioning.

4. Framework Agnostic with Tiny Adapters #

The entire library is written in Vanilla TypeScript. To support React, Vue, Svelte, or Solid, it provides incredibly thin wrapper adapters (all under 1 KB). This is a fantastic architectural choice because it means core bugs are fixed once for everyone, and it isn't tied to the lifecycle quirks of any specific framework.

5. Modern Tooling #

The repository is using modern tooling:

  • Bun for running scripts, testing, and building (bunfig.toml, bun.lock).
  • TypeScript with very strict and complex generics to ensure the item.template data matches the items array perfectly.
  • Zero Dependencies: Not a single runtime dependency in package.json, which is a breath of fresh air in the NPM ecosystem.

Conclusion Antigravity #

vlist is an incredibly high-quality piece of software. The author (Floor IO) clearly understands browser rendering pipelines deeply. 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 (like masonry/tables), this looks like an industry-leading option.

Floor #

Will you recommend this library in the future?

Antigravity #

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

Here is why it stands out as a strong recommendation:

  • Future-Proof Architecture: Because it is completely framework-agnostic at its core, you aren't locked into a specific ecosystem. If you migrate a project from React to SolidJS or Vue in the future, your complex virtual list logic (and the library powering it) can remain exactly the same. You just swap the tiny 0.5 KB adapter.
  • Solves the "Heavy Dependency" Problem: Virtual list libraries are notoriously heavy and often pull in a lot of transitives. vlist having zero dependencies and a base size of 10.7 KB (with perfect tree-shaking for unused features) means it won't bloat your bundle size.
  • 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. Usually, you have to piece together multiple different libraries to achieve all of this, which leads to inconsistent UI/UX.
  • Accessibility (A11y) Guarantee: Accessibility is incredibly hard to get right with virtualized DOM nodes. The fact that vlist handles DOM reordering for screen readers and 2D keyboard navigation out-of-the-box makes it safe to use in enterprise or government applications that require strict WCAG compliance.
  • Memory Safety: The attention to detail regarding memory management (DOM node pooling, avoiding object allocation during scroll frames, capping the internal element size to avoid browser layout crashes) means it is safe to use for massive datasets where other libraries might cause the browser tab to stutter or crash.

It is a remarkably well-engineered library. 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.

Floor #

Check the git history and tell me what you think about the development process and the timeline.

Antigravity #

Looking at 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.

Here is how the library evolved over time:

Phase 1: Solving the Hardest Problem First #

Interestingly, the very first features added after the initial commit weren't basic list things. They were:

feat(compression): add support for 1M+ items via manual wheel scrolling feat(scrollbar): add custom scrollbar for compressed mode

This shows the library was born out of a need to handle extreme scale (1 million+ items). Most libraries fail here because of browser pixel limits, so the author started by solving the hardest mathematical/rendering problem first (scroll compression).

Phase 2: The Early Pivot to Zero-Dependencies #

Very early in the commit history, there are commits like:

docs(readme): remove Tailwind CSS references chore: remove tailwind.config.js refactor: restructure to domain-driven architecture

It looks like the initial prototype might have used Tailwind, but the author quickly realized that to be a truly universal, lightweight library, it needed to have zero dependencies. The early pivot to a "domain-driven architecture" is what eventually became the highly modular Builder pattern (vlist().use(...)) it has today.

Phase 3: Adding Core Capabilities #

Once the architecture was solid and the massive-scale rendering was solved, they started backfilling standard virtual list requirements:

feat(render): add variable item height support feat(scroll): smooth scrollToIndex animation feat(scroll): add window/document scrolling support

Phase 4: Complex Layouts and Ecosystem #

With the vertical list perfected, the scope expanded significantly to support complex UIs:

feat(grid): add 2D grid layout mode feat(groups): add sticky headers / grouped lists feat(reverse): add reverse mode for chat-style UIs

Right after these layouts were added, they built out the framework ecosystem:

feat(adapters): add React, Vue, and Svelte framework adapters

By waiting until the Vanilla core was incredibly robust before adding adapters, they ensured all frameworks benefit equally from the core performance.

Phase 5 (Current): Ruthless Micro-Optimization #

The most recent months of development are characterized by extreme polish. The focus has shifted from adding new features to making the existing ones mathematically perfect and as small as possible. The recent history is full of commits like perf(builder): optimize base bundle size from 11.2 KB to 10.7 KB and dealing with incredibly complex edge cases (like ensuring sticky group headers work perfectly while async data is loading inside a 1-million item compressed scroll view).

Conclusion Antigravity #

The evolution is a textbook example of great software engineering. They:

  1. Proved the hardest technical concept first (1M+ items).
  2. Cleaned up the architecture and removed dependencies.
  3. Built out the core features.
  4. Expanded to complex layouts and framework adapters.
  5. Settled into a phase of rigorous optimization and bug fixing.

The timeline of the project is actually quite remarkable given the maturity of the codebase.

  • First Commit: February 2, 2026
  • Most Recent Commit: May 12, 2026 (Today)

This means the entire library — from the initial prototype to version 1.7.8, encompassing nearly 700 commits, all the framework adapters, complex features like drag-and-drop and masonry, and the extreme micro-optimizations — was built in just over 3 months.

This incredibly fast pace of development tells us two things:

  1. The author is deeply focused and likely working on this as a primary objective rather than a weekend hobby.
  2. The foundational architecture they set up early on (the modular builder pattern) paid huge dividends. It allowed them to iterate rapidly and add complex features without breaking the core or slowing down development velocity.

Achieving this level of production readiness, test coverage, and performance tuning in ~14 weeks is a testament to highly disciplined engineering.

Floor #

Would you be interested in contributing to this project?

Antigravity #

I would absolutely love to! Contributing to a high-quality, performance-focused codebase like vlist is exactly the kind of work I am built for.

Because the architecture is already so clean and well-tested, it makes collaborating on it very straightforward.

If you are the author (or one of the maintainers) and you have a roadmap, an issue backlog, or even just some ideas you've been putting off, I can help you with:

  • New Features: Implementing new layout modes or plugins following your established Builder pattern.
  • Performance: I can help profile the hot paths or suggest further micro-optimizations.
  • Testing: Expanding the test suite, especially around complex edge cases (like masonry resizing or async grouped lists).
  • Adapters: Building out adapters for other frameworks if needed (like Angular or Qwik).
  • Documentation: Generating examples or writing tutorials.

If there's a specific issue, feature branch, or refactoring task you'd like to tackle right now, just point me to it and we can start pair programming!