virtua 0.52.10 → 0.53.1

package/README.md

@@ -2,7 +2,7 @@
 
 ![npm](https://img.shields.io/npm/v/virtua) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua) ![npm](https://img.shields.io/npm/dw/virtua) [![Best of JS](https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=inokawa%2Fvirtua%26since=daily)](https://bestofjs.org/projects/virtua) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/inokawa/virtua) [![check](https://github.com/inokawa/virtua/actions/workflows/check.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/check.yml) [![demo](https://github.com/inokawa/virtua/actions/workflows/demo.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/demo.yml)
 
-> A zero-config, fast and small virtual list and grid component for [React](https://github.com/facebook/react), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/), [Svelte](https://svelte.dev/) and [Angular](https://angular.dev/).
+> A zero-config, fast and small virtual list, grid and masonry component for [React](https://github.com/facebook/react), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/), [Svelte](https://svelte.dev/) and [Angular](https://angular.dev/).
 
 ![list example](./example.gif) ![grid example](./example2.gif)
 
@@ -15,7 +15,7 @@ This project is a challenge to rethink virtualization. The goals are...
 - **Zero-config virtualization:** This library is designed to give the best performance without configuration. It also handles common hard things in the real world (dynamic size measurement, scroll position adjustment while reverse scrolling and imperative scrolling, iOS support, etc).
 - **Fast:** Natural virtual scrolling needs optimization in many aspects (eliminate frame drops by reducing CPU usage and GC, reduce [synchronous layout recalculation](https://gist.github.com/paulirish/5d52fb081b3570c81e3a), reduce visual jumps on repaint, optimize with CSS, optimize for JIT, optimize for frameworks, etc). We are trying to combine the best of them.
 - **Small:** Its bundle size should be small as much as possible to be friendly with modern web development. Currently components start from ~3kB gzipped and are tree-shakeable.
-- **Flexible:** Aiming to support many usecases - fixed size, dynamic size, horizontal scrolling, reverse scrolling, table, RTL, mobile, infinite scrolling, scroll restoration, DnD, keyboard navigation, sticky and more. See [live demo](#demo).
+- **Flexible:** Aiming to support many usecases - fixed size, dynamic size, horizontal scrolling, reverse scrolling, table, masonry, RTL, mobile, infinite scrolling, scroll restoration, DnD, keyboard navigation, sticky and more. See [live demo](#demo).
 - **Framework agnostic:** [React](https://react.dev/), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/), [Svelte](https://svelte.dev/) and [Angular](https://angular.dev/) are supported. We could support other frameworks in the future.
 
 ## Demo
@@ -33,7 +33,7 @@ If you want to support legacy browsers, you need polyfills.
 - [ResizeObserver](https://caniuse.com/?search=resizeobserver) is always required (e.g. [@juggle/resize-observer](https://github.com/juggle/resize-observer#switching-between-native-and-polyfilled-versions)).
 - [Scroll methods on elements](https://caniuse.com/element-scroll-methods) are always required (e.g. [element-scroll-polyfill](https://github.com/idmadj/element-scroll-polyfill)).
 - [CSS scroll-behavior](https://caniuse.com/?search=scroll-behavior) is required only if you call `scrollToIndex` with `smooth: true` (e.g. [scroll-behavior-polyfill](https://github.com/wessberg/scroll-behavior-polyfill)).
-- [CSS inset-inline-start](https://caniuse.com/mdn-css_properties_inset-inline-start) is required only if you set `horizontal: true`. It cannot be polyfilled so use `virtua@<=0.50` instead.
+- [CSS inset-inline-start](https://caniuse.com/mdn-css_properties_inset-inline-start) is required only if you set `horizontal: true` or use `VMasonry`. It cannot be polyfilled so use `virtua@<=0.50` instead.
 - [CSS subgrid](https://caniuse.com/css-subgrid) is required for VGrid.
 
 ## Getting started
@@ -44,48 +44,93 @@ If you want to support legacy browsers, you need polyfills.
 
 If you use ESM and webpack 5, use react >= 18 to avoid [Can't resolve `react/jsx-runtime` error](https://github.com/facebook/react/issues/20235).
 
-#### Vertical scroll
-
 ```tsx
 import { VList } from "virtua";
 
-// children
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
+
 export const App = () => {
   return (
-    <VList style={{ height: 800 }}>
-      {Array.from({ length: 1000 }).map((_, i) => (
+    <VList data={data} style={{ height: 800 }}>
+      {(item) => (
         <div
-          key={i}
+          key={item.id}
           style={{
-            height: Math.floor(Math.random() * 10) * 10 + 10,
-            borderBottom: "solid 1px gray",
+            height: item.size,
             background: "white",
+            borderBottom: "solid 1px #ccc",
           }}
         >
-          {i}
+          {item.id}
         </div>
-      ))}
+      )}
     </VList>
   );
 };
+```
+
+You can also pass elements as `children` directly instead of `data`.
+
+### Vue
+
+`vue >= 3.2` is required.
+
+```vue
+<script setup>
+import { VList } from "virtua/vue";
+
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
+</script>
+
+<template>
+  <VList :data="data" :style="{ height: '800px' }" #default="{ item }">
+    <div
+      :key="item.id"
+      :style="{
+        height: item.size + 'px',
+        background: 'white',
+        borderBottom: 'solid 1px #ccc',
+      }"
+    >
+      {{ item.id }}
+    </div>
+  </VList>
+</template>
+```
+
+### Solid
+
+`solid-js >= 1.0` is required.
+
+```tsx
+import { VList } from "virtua/solid";
+
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
 
-// or render prop
 export const App = () => {
-  const items = Array.from({ length: 1000 }).map(
-    () => Math.floor(Math.random() * 10) * 10 + 10,
-  );
   return (
-    <VList data={items} style={{ height: 800 }}>
-      {(d, i) => (
+    <VList data={data} style={{ height: "800px" }}>
+      {(item) => (
         <div
-          key={i}
           style={{
-            height: d,
-            borderBottom: "solid 1px gray",
+            height: item.size + "px",
             background: "white",
+            "border-bottom": "solid 1px #ccc",
           }}
         >
-          {i}
+          {item.id}
         </div>
       )}
     </VList>
@@ -93,89 +138,191 @@ export const App = () => {
 };
 ```
 
-#### Horizontal scroll
+### Svelte
+
+`svelte >= 5.0` is required.
+
+```svelte
+<script lang="ts">
+  import { VList } from "virtua/svelte";
+
+  const sizes = [20, 40, 80, 77];
+  const data = Array.from({ length: 1000 }).map((_, i) => ({
+    id: i,
+    size: sizes[i % 4],
+  }));
+</script>
+
+<VList {data} style="height: 800px;" getKey={(item) => item.id}>
+  {#snippet children(item)}
+    <div
+      style="
+        height: {item.size}px;
+        background: white;
+        border-bottom: solid 1px #ccc;
+      "
+    >
+      {item.id}
+    </div>
+  {/snippet}
+</VList>
+```
+
+### Angular
+
+`@angular/core >= 20` is required. The components are zoneless-ready and work with both zone.js and [`provideZonelessChangeDetection`](https://angular.dev/api/core/provideZonelessChangeDetection).
+
+```ts
+import { Component } from "@angular/core";
+import { VList } from "virtua/angular";
+
+const sizes = [20, 40, 80, 77];
+
+@Component({
+  selector: "app-root",
+  imports: [VList],
+  template: `
+    <virtua-vlist [data]="data" [getKey]="getKey" style="height: 800px;">
+      <ng-template let-item>
+        <div
+          [style.height.px]="item.size"
+          style="background: white; border-bottom: solid 1px #ccc;"
+        >
+          {{ item.id }}
+        </div>
+      </ng-template>
+    </virtua-vlist>
+  `,
+})
+export class App {
+  protected readonly data = Array.from({ length: 1000 }).map((_, i) => ({
+    id: i,
+    size: sizes[i % 4],
+  }));
+  protected readonly getKey = (item: { id: number }) => item.id;
+}
+```
+
+### Other bindings
+
+- [vanilla-virtua](https://github.com/aabccd021/vanilla-virtua): virtua for vanilla js
+
+## Usage
+
+The examples are written in React, but the same components and props are available in all frameworks.
+
+### Horizontal scroll
 
 ```tsx
 import { VList } from "virtua";
 
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
+
 export const App = () => {
   return (
-    <VList style={{ height: 400 }} horizontal>
-      {Array.from({ length: 1000 }).map((_, i) => (
+    <VList data={data} style={{ height: 400 }} horizontal>
+      {(item) => (
         <div
-          key={i}
+          key={item.id}
           style={{
-            width: Math.floor(Math.random() * 10) * 10 + 10,
-            borderRight: "solid 1px gray",
+            width: item.size,
             background: "white",
+            borderRight: "solid 1px #ccc",
           }}
         >
-          {i}
+          {item.id}
         </div>
-      ))}
+      )}
     </VList>
   );
 };
 ```
 
-#### Customization
+### Custom scroll container
 
 `VList` is a recommended solution which works like a drop-in replacement of simple list built with scrollable `div` (or removed [virtual-scroller element](https://github.com/WICG/virtual-scroller)). For more complicated styling or markup, use `Virtualizer`.
 
 ```tsx
 import { Virtualizer } from "virtua";
 
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
+const headerHeight = 40;
+
 export const App = () => {
   return (
-    <div style={{ overflowY: "auto", overflowAnchor: "none", height: 800 }}>
-      <div style={{ height: 40 }}>header</div>
-      <Virtualizer startMargin={40}>
-        {Array.from({ length: 1000 }).map((_, i) => (
+    <div
+      style={{
+        height: 800,
+        overflowY: "auto",
+        // opt out browser's scroll anchoring on header/footer because it will conflict with scroll anchoring of virtualizer
+        overflowAnchor: "none",
+      }}
+    >
+      <div style={{ height: headerHeight }}>header</div>
+      <Virtualizer data={data} startMargin={headerHeight}>
+        {(item) => (
           <div
-            key={i}
+            key={item.id}
             style={{
-              height: Math.floor(Math.random() * 10) * 10 + 10,
-              borderBottom: "solid 1px gray",
+              height: item.size,
               background: "white",
+              borderBottom: "solid 1px #ccc",
             }}
           >
-            {i}
+            {item.id}
           </div>
-        ))}
+        )}
       </Virtualizer>
+      <div style={{ height: 600 }}>footer</div>
     </div>
   );
 };
 ```
 
-#### Window scroll
+### Window scroll
 
 ```tsx
 import { WindowVirtualizer } from "virtua";
 
+const sizes = [20, 40, 80, 77];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+}));
+
 export const App = () => {
   return (
     <div style={{ padding: 200 }}>
-      <WindowVirtualizer>
-        {Array.from({ length: 1000 }).map((_, i) => (
+      <WindowVirtualizer data={data}>
+        {(item) => (
           <div
-            key={i}
+            key={item.id}
             style={{
-              height: Math.floor(Math.random() * 10) * 10 + 10,
-              borderBottom: "solid 1px gray",
+              height: item.size,
               background: "white",
+              borderBottom: "solid 1px #ccc",
             }}
           >
-            {i}
+            {item.id}
           </div>
-        ))}
+        )}
       </WindowVirtualizer>
     </div>
   );
 };
 ```
 
-#### Tabular data
+### Tabular data
+
+For data with rows and columns such as a table, use `VGrid`. It virtualizes on both axes.
 
 ```tsx
 import { VGrid } from "virtua";
@@ -189,32 +336,38 @@ const columns = [
   { key: "bio", width: 480 },
 ] as const;
 
-const rows = Array.from({ length: 10000 }, (_, i) => ({
-  id: i,
-  name: `User ${i}`,
-  email: `user${i}@example.com`,
-  age: 20 + (i % 50),
-  joined: new Date(2020, 0, 1 + i).toDateString(),
-  bio: `Hello, I'm user ${i}.`,
-}));
+const rows = [
+  // the header row has no data
+  null,
+  ...Array.from({ length: 10000 }).map((_, i) => ({
+    id: i,
+    name: `User ${i}`,
+    email: `user${i}@example.com`,
+    age: 20 + (i % 50),
+    joined: new Date(2020, 0, 1 + i).toDateString(),
+    bio: `Hello, I'm user ${i}.`,
+  })),
+];
 
 export const App = () => {
   return (
     <VGrid
-      style={{ height: 800, border: "solid 1px gray", background: "white" }}
+      style={{ height: 800, border: "solid 1px #ccc", background: "white" }}
       rows={rows}
       rowHeight={40}
       cols={columns}
       colWidth="width"
+      headerRows={1}
     >
       {(row, col) => (
         <div
           style={{
-            borderRight: "solid 1px gray",
-            borderBottom: "solid 1px gray",
+            borderRight: "solid 1px #ccc",
+            borderBottom: "solid 1px #ccc",
+            background: row === null ? "lightgray" : undefined,
           }}
         >
-          {row[col.key]}
+          {row === null ? col.key : row[col.key]}
         </div>
       )}
     </VGrid>
@@ -222,133 +375,47 @@ export const App = () => {
 };
 ```
 
-### Vue
-
-`vue >= 3.2` is required.
+### Masonry
 
-```vue
-<script setup>
-import { VList } from "virtua/vue";
-
-const sizes = [20, 40, 180, 77];
-const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4]);
-</script>
-
-<template>
-  <VList :data="data" :style="{ height: '800px' }" #default="{ item, index }">
-    <div
-      :key="index"
-      :style="{
-        height: item + 'px',
-        borderBottom: 'solid 1px #ccc',
-        background: 'white',
-      }"
-    >
-      {{ index }}
-    </div>
-  </VList>
-</template>
-```
-
-### Solid
-
-`solid-js >= 1.0` is required.
+For items with different heights laid out in columns such as a gallery, use `VMasonry`.
 
 ```tsx
-import { VList } from "virtua/solid";
+import { VMasonry } from "virtua";
 
-export const App = () => {
-  const sizes = [20, 40, 180, 77];
-  const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4]);
+const sizes = [100, 180, 140, 220];
+const colors = ["skyblue", "pink", "khaki", "lightgreen", "plum"];
+const data = Array.from({ length: 1000 }).map((_, i) => ({
+  id: i,
+  size: sizes[i % 4],
+  color: colors[i % 5],
+}));
 
+export const App = () => {
   return (
-    <VList data={data} style={{ height: "800px" }}>
-      {(d, i) => (
+    <VMasonry data={data} lanes={3} gap={8} style={{ height: 800 }}>
+      {(item) => (
         <div
+          key={item.id}
           style={{
-            height: d + "px",
-            "border-bottom": "solid 1px #ccc",
-            background: "white",
+            height: item.size,
+            background: item.color,
           }}
         >
-          {i()}
+          {item.id}
         </div>
       )}
-    </VList>
+    </VMasonry>
   );
 };
 ```
 
-### Svelte
-
-`svelte >= 5.0` is required.
-
-```svelte
-<script lang="ts">
-  import { VList } from "virtua/svelte";
+### More examples
 
-  const sizes = [20, 40, 180, 77];
-
-  const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4]);
-</script>
-
-<VList {data} style="height: 800px;" getKey={(_, i) => i}>
-  {#snippet children(item, index)}
-    <div
-      style="
-        height: {item}px;
-        border-bottom: solid 1px #ccc;
-        background: white;
-      "
-    >
-      {index}
-    </div>
-  {/snippet}
-</VList>
-```
-
-### Angular
-
-`@angular/core >= 20` is required. The components are zoneless-ready and work with both zone.js and [`provideZonelessChangeDetection`](https://angular.dev/api/core/provideZonelessChangeDetection).
-
-```ts
-import { Component } from "@angular/core";
-import { VList } from "virtua/angular";
-
-const sizes = [20, 40, 180, 77];
-
-@Component({
-  selector: "app-root",
-  imports: [VList],
-  template: `
-    <virtua-vlist [data]="data" [getKey]="getKey" style="height: 800px;">
-      <ng-template let-item let-index="index">
-        <div
-          [style.height.px]="item"
-          style="background: white; border-bottom: solid 1px #ccc;"
-        >
-          {{ index }}
-        </div>
-      </ng-template>
-    </virtua-vlist>
-  `,
-})
-export class App {
-  protected readonly data = Array.from({ length: 1000 }).map(
-    (_, i) => sizes[i % 4]!,
-  );
-  protected readonly getKey = (_: number, i: number) => i;
-}
-```
-
-### Other bindings
-
-- [vanilla-virtua](https://github.com/aabccd021/vanilla-virtua): virtua for vanilla js
+See [demo](https://inokawa.github.io/virtua/) and [its source code](./stories).
 
 ## Documentation
 
 - [API reference](./docs/API.md)
-- [Storybook examples](./stories) for more usages
 - [DeepWiki](https://deepwiki.com/inokawa/virtua)
 
 ### FAQs
@@ -408,11 +475,17 @@ It may be dispatched by ResizeObserver in this lib [as described in spec](https:
 
 Especially for `webpack-dev-server`, [you can filter out the specific error with `devServer.client.overlay.runtimeErrors` option](https://webpack.js.org/configuration/dev-server/#overlay).
 
-#### Why my items are squashed(or rendered inconsistently) on resize/add/remove?
+#### Why are my items squashed, overlapped or rendered inconsistently on resize/add/remove/reorder?
 
-Maybe you forgot to pass `key` prop to each items, or the keys are not unique. Item sizes are stored per key.
+Check that each item has a unique key, such as the id of your data, not its index.
 
-And do not use index of items as `key`, especially when you want to toggle `shift` prop to `true`. Prepending will increment every indexes of items and that will cause unexpected behavior.
+- React: `key` of the element of each item
+- Vue: `key` of the root element in the default slot
+- Solid: the item of `data` itself, so keep the same reference for the same item
+- Svelte: `getKey` prop
+- Angular: `getKey` input
+
+If it still happens, the `shift` prop may be misused.
 
 #### Why `VListHandle.viewportSize` is 0 on mount?
 
@@ -426,32 +499,52 @@ This package uses [exports of package.json](https://nodejs.org/api/packages.html
 
 ### Features
 
-|                                                                                                                                                                | [virtua](https://github.com/inokawa/virtua)                                                                      | [react-virtuoso](https://github.com/petyosi/react-virtuoso)                                                                      | [react-window](https://github.com/bvaughn/react-window)                                                                      | [react-virtualized](https://github.com/bvaughn/react-virtualized)                                                                                                      | [@tanstack/react-virtual](https://github.com/TanStack/virtual)                                                                                     |
-| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Bundle size                                                                                                                                                    | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua)](https://bundlephobia.com/package/virtua) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtuoso)](https://bundlephobia.com/package/react-virtuoso) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-window)](https://bundlephobia.com/package/react-window) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtualized)](https://bundlephobia.com/package/react-virtualized)                                 | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tanstack/react-virtual)](https://bundlephobia.com/package/@tanstack/react-virtual) |
-| Vertical scroll                                                                                                                                                | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | ✅                                                                                                                                                                     | 🟠 (needs customization)                                                                                                                           |
-| Horizontal scroll                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | ✅                                                                                                                                                                     | 🟠 (needs customization)                                                                                                                           |
-| Horizontal scroll in RTL direction                                                                                                                             | ✅                                                                                                               | ❌                                                                                                                               | ✅                                                                                                                           | ❌                                                                                                                                                                     | 🟠 (isRtl)                                                                                                                                         |
-| Grid (Virtualization for two dimensions)                                                                                                                       | ✅ (VGrid)                                                                                                       | ❌                                                                                                                               | ✅ ([Grid](https://react-window.vercel.app/grid/grid))                                                                       | ✅ ([Grid](https://github.com/bvaughn/react-virtualized/blob/master/docs/Grid.md))                                                                                     | 🟠 (needs customization)                                                                                                                           |
-| Tabular data (Columns with headers)                                                                                                                            | ✅ (VGrid)                                                                                                       | ✅ (TableVirtuoso)                                                                                                               | ✅ ([Supported](https://react-window.vercel.app/list/tabular-data))                                                          | ✅ ([Table](https://github.com/bvaughn/react-virtualized/blob/master/docs/Table.md))                                                                                   | 🟠 (needs customization)                                                                                                                           |
-| HTML table element                                                                                                                                             | 🟠 (needs customization)                                                                                         | ✅ (TableVirtuoso)                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                                     | 🟠 (needs customization)                                                                                                                           |
-| Masonry                                                                                                                                                        | ❌                                                                                                               | ✅ (VirtuosoMasonry)                                                                                                             | ❌                                                                                                                           | ✅ ([Masonry](https://github.com/bvaughn/react-virtualized/blob/master/docs/Masonry.md))                                                                               | 🟠 (needs customization)                                                                                                                           |
-| Window scroller                                                                                                                                                | ✅ (WindowVirtualizer)                                                                                           | ✅                                                                                                                               | ❌                                                                                                                           | ✅ ([WindowScroller](https://github.com/bvaughn/react-virtualized/blob/master/docs/WindowScroller.md))                                                                 | ✅ (useWindowVirtualizer)                                                                                                                          |
-| Dynamic list size                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | 🟠 (needs [AutoSizer](https://github.com/bvaughn/react-virtualized/blob/master/docs/AutoSizer.md))                                                                     | ✅                                                                                                                                                 |
-| Dynamic item size                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | 🟠 (needs additional codes and has wrong destination when scrolling to item imperatively)                                    | 🟠 (needs [CellMeasurer](https://github.com/bvaughn/react-virtualized/blob/master/docs/CellMeasurer.md) and has wrong destination when scrolling to item imperatively) | ✅                                                                                                                                                 |
-| Reverse scroll                                                                                                                                                 | ✅                                                                                                               | ✅                                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                                     | ❌                                                                                                                                                 |
-| Reverse scroll in iOS Safari                                                                                                                                   | 🟠 ([user must release scroll](https://github.com/inokawa/virtua/issues/473))                                    | 🟠 ([has glitch with unknown sized items](https://github.com/petyosi/react-virtuoso/issues/945))                                 | ❌                                                                                                                           | ❌                                                                                                                                                                     | ❌                                                                                                                                                 |
-| Infinite scroll                                                                                                                                                | ✅                                                                                                               | ✅                                                                                                                               | 🟠 (needs [react-window-infinite-loader](https://github.com/bvaughn/react-window-infinite-loader))                           | 🟠 (needs [InfiniteLoader](https://github.com/bvaughn/react-virtualized/blob/master/docs/InfiniteLoader.md))                                                           | ✅                                                                                                                                                 |
-| Reverse (bi-directional) infinite scroll                                                                                                                       | ✅                                                                                                               | ✅                                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                                     | ❌                                                                                                                                                 |
-| Scroll restoration                                                                                                                                             | ✅                                                                                                               | ✅ (getState)                                                                                                                    | ❌                                                                                                                           | ❌                                                                                                                                                                     | ❌                                                                                                                                                 |
-| Smooth scroll                                                                                                                                                  | ✅                                                                                                               | ✅                                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                                     | ✅                                                                                                                                                 |
-| SSR support                                                                                                                                                    | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | ✅                                                                                                                                                                     | ✅                                                                                                                                                 |
-| Render React Server Components (RSC) as children                                                                                                               | ✅                                                                                                               | ❌                                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                                     | 🟠(needs customization)                                                                                                                            |
-| Display exceeding [browser's max element size](https://stackoverflow.com/questions/10882769/do-the-browsers-have-a-maximum-height-for-the-body-document) limit | ❌                                                                                                               | ❌                                                                                                                               | ❌                                                                                                                           | ✅                                                                                                                                                                     | ❌                                                                                                                                                 |
+|                                                                                                                                                                | [virtua](https://github.com/inokawa/virtua)                                                                      | [react-virtuoso](https://github.com/petyosi/react-virtuoso)                                                                      | [react-window](https://github.com/bvaughn/react-window)                                                                      | [@tanstack/react-virtual](https://github.com/TanStack/virtual)                                                                                     | [react-virtualized](https://github.com/bvaughn/react-virtualized)                                                                                                      |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bundle size                                                                                                                                                    | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua)](https://bundlephobia.com/package/virtua) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtuoso)](https://bundlephobia.com/package/react-virtuoso) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-window)](https://bundlephobia.com/package/react-window) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tanstack/react-virtual)](https://bundlephobia.com/package/@tanstack/react-virtual) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtualized)](https://bundlephobia.com/package/react-virtualized)                                 |
+| Vertical scroll                                                                                                                                                | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | 🟠 (needs customization)                                                                                                                           | ✅                                                                                                                                                                     |
+| Horizontal scroll                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | 🟠 (needs customization)                                                                                                                           | ✅                                                                                                                                                                     |
+| Horizontal scroll in RTL direction                                                                                                                             | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | 🟠 (isRtl)                                                                                                                                         | ❌                                                                                                                                                                     |
+| Grid (Virtualization for two dimensions)                                                                                                                       | ✅ (VGrid)                                                                                                       | ❌                                                                                                                               | ✅ ([Grid](https://react-window.vercel.app/grid/grid))                                                                       | 🟠 (needs customization)                                                                                                                           | ✅ ([Grid](https://github.com/bvaughn/react-virtualized/blob/master/docs/Grid.md))                                                                                     |
+| Tabular data (Columns with headers)                                                                                                                            | ✅ (VGrid)                                                                                                       | ✅ (TableVirtuoso)                                                                                                               | ✅ ([Supported](https://react-window.vercel.app/list/tabular-data))                                                          | 🟠 (needs customization)                                                                                                                           | ✅ ([Table](https://github.com/bvaughn/react-virtualized/blob/master/docs/Table.md))                                                                                   |
+| HTML table element                                                                                                                                             | 🟠 (needs customization)                                                                                         | ✅ (TableVirtuoso)                                                                                                               | ❌                                                                                                                           | 🟠 (needs customization)                                                                                                                           | ❌                                                                                                                                                                     |
+| Masonry                                                                                                                                                        | ✅ (VMasonry)                                                                                                    | ✅ (VirtuosoMasonry)                                                                                                             | ❌                                                                                                                           | 🟠 (lanes)                                                                                                                                         | ✅ ([Masonry](https://github.com/bvaughn/react-virtualized/blob/master/docs/Masonry.md))                                                                               |
+| Window scroller                                                                                                                                                | ✅ (WindowVirtualizer)                                                                                           | ✅                                                                                                                               | ❌                                                                                                                           | ✅ (useWindowVirtualizer)                                                                                                                          | ✅ ([WindowScroller](https://github.com/bvaughn/react-virtualized/blob/master/docs/WindowScroller.md))                                                                 |
+| Dynamic list size                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | ✅                                                                                                                           | ✅                                                                                                                                                 | 🟠 (needs [AutoSizer](https://github.com/bvaughn/react-virtualized/blob/master/docs/AutoSizer.md))                                                                     |
+| Dynamic item size                                                                                                                                              | ✅                                                                                                               | ✅                                                                                                                               | ✅ (useDynamicRowHeight)                                                                                                     | ✅ (measureElement)                                                                                                                                | 🟠 (needs [CellMeasurer](https://github.com/bvaughn/react-virtualized/blob/master/docs/CellMeasurer.md) and has wrong destination when scrolling to item imperatively) |
+| Reverse scroll                                                                                                                                                 | ✅                                                                                                               | ✅                                                                                                                               | ❌                                                                                                                           | ✅ (anchorTo)                                                                                                                                      | ❌                                                                                                                                                                     |
+| Reverse scroll in iOS Safari                                                                                                                                   | 🟠 ([user must release scroll](https://github.com/inokawa/virtua/issues/473))                                    | 🟠 ([has glitch with unknown sized items](https://github.com/petyosi/react-virtuoso/issues/945))                                 | ❌                                                                                                                           | 🟠                                                                                                                                                 | ❌                                                                                                                                                                     |
+| Infinite scroll                                                                                                                                                | ✅                                                                                                               | ✅                                                                                                                               | 🟠 (needs [react-window-infinite-loader](https://github.com/bvaughn/react-window-infinite-loader))                           | ✅                                                                                                                                                 | 🟠 (needs [InfiniteLoader](https://github.com/bvaughn/react-virtualized/blob/master/docs/InfiniteLoader.md))                                                           |
+| Reverse (bi-directional) infinite scroll                                                                                                                       | ✅                                                                                                               | ✅                                                                                                                               | ❌                                                                                                                           | ✅ (anchorTo)                                                                                                                                      | ❌                                                                                                                                                                     |
+| Scroll restoration                                                                                                                                             | ✅                                                                                                               | ✅ (getState)                                                                                                                    | ❌                                                                                                                           | ✅ (takeSnapshot)                                                                                                                                  | ❌                                                                                                                                                                     |
+| Smooth scroll                                                                                                                                                  | ✅                                                                                                               | ✅                                                                                                                               | 🟠 ([not with useDynamicRowHeight](https://react-window.vercel.app/list/dynamic-row-height))                                 | ✅                                                                                                                                                 | ❌                                                                                                                                                                     |
+| SSR support                                                                                                                                                    | ✅ (ssrCount)                                                                                                    | ✅ (initialItemCount)                                                                                                            | ✅ (defaultHeight)                                                                                                           | ✅ (initialRect)                                                                                                                                   | ✅                                                                                                                                                                     |
+| Render React Server Components (RSC) as children                                                                                                               | ✅                                                                                                               | ❌                                                                                                                               | ❌                                                                                                                           | 🟠 (needs customization)                                                                                                                           | ❌                                                                                                                                                                     |
+| Display exceeding [browser's max element size](https://stackoverflow.com/questions/10882769/do-the-browsers-have-a-maximum-height-for-the-body-document) limit | ❌                                                                                                               | ❌                                                                                                                               | ❌                                                                                                                           | ❌                                                                                                                                                 | ✅                                                                                                                                                                     |
+
+- ✅ - Built-in supported
+- 🟠 - Supported but partial, limited or requires some user custom code
+- ❌ - Not officially supported
+
+### Grid features
+
+|                                                                                                                                                                | [virtua](https://github.com/inokawa/virtua) (VGrid)                                                              | [AG Grid Community](https://www.ag-grid.com/react-data-grid/)                                                                                                                              | [MUI X Data Grid](https://mui.com/x/react-data-grid/)                                                                                | [react-data-grid](https://github.com/Comcast/react-data-grid)                                                                      | [@virtuoso.dev/data-table](https://virtuoso.dev/data-table/)                                                                                         | [react-window](https://github.com/bvaughn/react-window) (Grid)                                                               | [@tanstack/react-virtual](https://github.com/TanStack/virtual)                                                                                     |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bundle size                                                                                                                                                    | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua)](https://bundlephobia.com/package/virtua) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/ag-grid-react)](https://bundlephobia.com/package/ag-grid-react)                                                             | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@mui/x-data-grid)](https://bundlephobia.com/package/@mui/x-data-grid) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-data-grid)](https://bundlephobia.com/package/react-data-grid) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@virtuoso.dev/data-table)](https://bundlephobia.com/package/@virtuoso.dev/data-table) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-window)](https://bundlephobia.com/package/react-window) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tanstack/react-virtual)](https://bundlephobia.com/package/@tanstack/react-virtual) |
+| Row / column virtualization                                                                                                                                    | ✅                                                                                                               | ✅                                                                                                                                                                                         | 🟠 (rows are limited to 100 per page, 💰 [Pro](https://mui.com/x/react-data-grid/virtualization/#row-virtualization) for more)       | ✅                                                                                                                                 | ✅                                                                                                                                                   | ✅                                                                                                                           | 🟠 (needs customization)                                                                                                                           |
+| Dynamic row height / column width                                                                                                                              | ✅ (auto)                                                                                                        | ✅ ([autoHeight](https://www.ag-grid.com/react-data-grid/row-height/#auto-row-height) / [autoSizeStrategy](https://www.ag-grid.com/react-data-grid/column-sizing/#continuous-auto-sizing)) | 🟠 (only row height, column width needs [autosizing on demand](https://mui.com/x/react-data-grid/column-dimensions/#autosizing))     | 🟠 (only column width, measured once)                                                                                              | 🟠 (only row height, column width is [measured from header cells](https://virtuoso.dev/data-table/columns/column-layout/))                           | ❌                                                                                                                           | 🟠 (measureElement)                                                                                                                                |
+| Pinned rows / columns                                                                                                                                          | ✅                                                                                                               | ✅                                                                                                                                                                                         | 💰 (Pro, [rows](https://mui.com/x/react-data-grid/row-pinning/) / [columns](https://mui.com/x/react-data-grid/column-pinning/))      | ✅                                                                                                                                 | 🟠 (only columns)                                                                                                                                    | ❌                                                                                                                           | 🟠 (rangeExtractor)                                                                                                                                |
+| Row / column spanning                                                                                                                                          | ✅                                                                                                               | ✅                                                                                                                                                                                         | 🟠 ([row spanning needs fixed row height](https://mui.com/x/react-data-grid/row-spanning/))                                          | 🟠 (only columns)                                                                                                                  | 🟠 (only [column group headers](https://virtuoso.dev/data-table/columns/column-groups/))                                                             | ❌                                                                                                                           | ❌                                                                                                                                                 |
+| Sticky group rows                                                                                                                                              | ✅ (sectionRows)                                                                                                 | 💰 ([Enterprise](https://www.ag-grid.com/react-data-grid/grouping-opening-groups/))                                                                                                        | ❌                                                                                                                                   | ❌                                                                                                                                 | ✅ ([Grouped rows](https://virtuoso.dev/data-table/grouped-rows/))                                                                                   | ❌                                                                                                                           | 🟠 (rangeExtractor)                                                                                                                                |
+| SSR support                                                                                                                                                    | ❌                                                                                                               | ❌                                                                                                                                                                                         | ❌                                                                                                                                   | 🟠 (limited to the first few rows)                                                                                                 | ❌                                                                                                                                                   | ✅ (defaultHeight, defaultWidth)                                                                                             | ✅ (initialRect)                                                                                                                                   |
+| Window scroller                                                                                                                                                | ❌                                                                                                               | ❌                                                                                                                                                                                         | ❌                                                                                                                                   | ❌                                                                                                                                 | ✅ (useWindowScroll)                                                                                                                                 | ❌                                                                                                                           | ✅ (useWindowVirtualizer)                                                                                                                          |
+| Display exceeding [browser's max element size](https://stackoverflow.com/questions/10882769/do-the-browsers-have-a-maximum-height-for-the-body-document) limit | ❌                                                                                                               | ✅ ([Stretching](https://www.ag-grid.com/react-data-grid/massive-row-count/))                                                                                                              | ❌                                                                                                                                   | ❌                                                                                                                                 | ❌                                                                                                                                                   | ❌                                                                                                                           | ❌                                                                                                                                                 |
+| Use with [TanStack Table](https://github.com/TanStack/table)                                                                                                   | ✅ ([example](./stories/react/advanced/With%20tanstack-table.stories.tsx))                                       | ❌                                                                                                                                                                                         | ❌                                                                                                                                   | ❌                                                                                                                                 | ❌                                                                                                                                                   | 🟠 (needs customization)                                                                                                     | ✅ ([guide](https://tanstack.com/table/latest/docs/framework/react/guide/virtualization))                                                          |
 
 - ✅ - Built-in supported
 - 🟠 - Supported but partial, limited or requires some user custom code
 - ❌ - Not officially supported
+- 💰 - Supported only in paid plans
 
 ### Benchmark