feat(table): virtualization

.changeset/fresh-windows-check.md

@@ -0,0 +1,5 @@
+---
+"@heroui/table": patch
+---
+
+Virtualization support added to Table component (#3697)

apps/docs/config/routes.json

@@ -423,7 +423,8 @@
           "key": "table",
           "title": "Table",
           "keywords": "table, data display, grid, spreadsheet",
-          "path": "/docs/components/table.mdx"
+          "path": "/docs/components/table.mdx",
+          "updated": true
         },
         {
           "key": "tabs",

apps/docs/content/components/table/index.ts

@@ -19,6 +19,10 @@ import asyncPagination from "./async-pagination";
 import infinitePagination from "./infinite-pagination";
 import useCase from "./use-case";
 import customStyles from "./custom-styles";
+import virtualization from "./virtualization";
+import virtualizationCustomItemHeight from "./virtualization-custom-row-height";
+import virtualizationCustomMaxTableHeight from "./virtualization-custom-max-table-height";
+import virtualizationTenThousand from "./virtualization-ten-thousand";
 
 export const tableContent = {
   usage,
@@ -42,4 +46,8 @@ export const tableContent = {
   infinitePagination,
   useCase,
   customStyles,
+  virtualization,
+  virtualizationCustomItemHeight,
+  virtualizationCustomMaxTableHeight,
+  virtualizationTenThousand,
 };

apps/docs/content/components/table/virtualization-custom-max-table-height.raw.jsx

@@ -0,0 +1,37 @@
+import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from "@nextui-org/react";
+
+function generateRows(count) {
+  return Array.from({length: count}, (_, index) => ({
+    key: index.toString(),
+    name: `Item ${index + 1}`,
+    value: `Value ${index + 1}`,
+  }));
+}
+
+export default function App() {
+  const rows = generateRows(500);
+  const columns = [
+    {key: "name", label: "Name"},
+    {key: "value", label: "Value"},
+  ];
+
+  return (
+    <Table
+      isVirtualized
+      aria-label="Example of virtualized table with a large dataset"
+      maxTableHeight={300}
+      rowHeight={40}
+    >
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+  );
+}

apps/docs/content/components/table/virtualization-custom-max-table-height.ts

@@ -0,0 +1,9 @@
+import App from "./virtualization-custom-max-table-height.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/table/virtualization-custom-row-height.raw.jsx

@@ -0,0 +1,37 @@
+import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from "@nextui-org/react";
+
+function generateRows(count) {
+  return Array.from({length: count}, (_, index) => ({
+    key: index.toString(),
+    name: `Item ${index + 1}`,
+    value: `Value ${index + 1}`,
+  }));
+}
+
+export default function App() {
+  const rows = generateRows(500);
+  const columns = [
+    {key: "name", label: "Name"},
+    {key: "value", label: "Value"},
+  ];
+
+  return (
+    <Table
+      isVirtualized
+      aria-label="Example of virtualized table with a large dataset"
+      maxTableHeight={500}
+      rowHeight={70}
+    >
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+  );
+}

apps/docs/content/components/table/virtualization-custom-row-height.ts

@@ -0,0 +1,9 @@
+import App from "./virtualization-custom-row-height.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/table/virtualization-ten-thousand.raw.jsx

@@ -0,0 +1,37 @@
+import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from "@nextui-org/react";
+
+function generateRows(count) {
+  return Array.from({length: count}, (_, index) => ({
+    key: index.toString(),
+    name: `Item ${index + 1}`,
+    value: `Value ${index + 1}`,
+  }));
+}
+
+export default function App() {
+  const rows = generateRows(10000);
+  const columns = [
+    {key: "name", label: "Name"},
+    {key: "value", label: "Value"},
+  ];
+
+  return (
+    <Table
+      isVirtualized
+      aria-label="Example of virtualized table with a large dataset"
+      maxTableHeight={500}
+      rowHeight={40}
+    >
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+  );
+}

apps/docs/content/components/table/virtualization-ten-thousand.ts

@@ -0,0 +1,9 @@
+import App from "./virtualization-ten-thousand.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/components/table/virtualization.raw.jsx

@@ -0,0 +1,37 @@
+import {Table, TableBody, TableCell, TableColumn, TableHeader, TableRow} from "@nextui-org/react";
+
+function generateRows(count) {
+  return Array.from({length: count}, (_, index) => ({
+    key: index.toString(),
+    name: `Item ${index + 1}`,
+    value: `Value ${index + 1}`,
+  }));
+}
+
+export default function App() {
+  const rows = generateRows(500);
+  const columns = [
+    {key: "name", label: "Name"},
+    {key: "value", label: "Value"},
+  ];
+
+  return (
+    <Table
+      isVirtualized
+      aria-label="Example of virtualized table with a large dataset"
+      maxTableHeight={500}
+      rowHeight={40}
+    >
+      <TableHeader columns={columns}>
+        {(column) => <TableColumn key={column.key}>{column.label}</TableColumn>}
+      </TableHeader>
+      <TableBody items={rows}>
+        {(item) => (
+          <TableRow key={item.key}>
+            {(columnKey) => <TableCell>{item[columnKey]}</TableCell>}
+          </TableRow>
+        )}
+      </TableBody>
+    </Table>
+  );
+}

apps/docs/content/components/table/virtualization.ts

@@ -0,0 +1,9 @@
+import App from "./virtualization.raw.jsx?raw";
+
+const react = {
+  "/App.jsx": App,
+};
+
+export default {
+  ...react,
+};

apps/docs/content/docs/components/table.mdx

@@ -317,6 +317,36 @@ import { useAsyncList } from "@react-stately/data";
   iframeSrc="/examples/table/infinite-pagination"
 />
 
+
+### Virtualization
+
+Table supports virtualization, which allows efficient rendering of large lists by only rendering items that are visible in the viewport. You can enable virtualization by setting the `isVirtualized` prop to `true`.
+
+<CodeDemo
+  title="Virtualization"
+  files={tableContent.virtualization}
+/>
+
+> **Note**: The virtualization strategy is based on the [@tanstack/react-virtual](https://tanstack.com/virtual/latest) package, which provides efficient rendering of large lists by only rendering items that are visible in the viewport.
+
+#### Ten Thousand Items
+
+Here's an example of using virtualization with 10,000 items.
+
+<CodeDemo title="Ten Thousand Items" files={tableContent.virtualizationTenThousand} />
+
+#### Max Table Height
+
+The `maxTableHeight` prop is used to set the maximum height of the table. This is required when using virtualization. By default, it's set to `600`.
+
+<CodeDemo title="Max Table Height" files={tableContent.virtualizationCustomMaxTableHeight} />
+
+#### Custom Row Height
+
+The `rowHeight` prop is used to set the height of each row in the table. This is required when using virtualization. By default, it's set to `40`.
+
+<CodeDemo title="Custom Row Height" files={tableContent.virtualizationCustomItemHeight} />
+
 ### Use Case Example
 
 When creating a table, you usually need core functionalities like sorting, pagination, and filtering. In the
@@ -456,6 +486,24 @@ You can customize the `Table` component by passing custom Tailwind CSS classes t
       type: "none | sm | md | lg",
       description: "The shadow size of the table.",
       default: "sm"
+    },
+        {
+      attribute: "maxTableHeight",
+      type: "number",
+      description: "The maximum height of the table in pixels. Required when using virtualization.",
+      default: 600
+    },
+    {
+      attribute: "rowHeight",
+      type: "number", 
+      description: "The fixed height of each row item in pixels. Required when using virtualization.",
+      default: 40
+    },
+    {
+      attribute: "isVirtualized",
+      type: "boolean",
+      description: "Whether to enable virtualization. By default, it's enabled when the number of items exceeds 50.",
+      default: "undefined"
     },
     {
       attribute: "hideHeader",

apps/docs/package.json

@@ -53,7 +53,7 @@
     "@react-stately/tree": "3.8.7",
     "@rehooks/local-storage": "^2.4.5",
     "@stackblitz/sdk": "^1.11.0",
-    "@tanstack/react-virtual": "3.11.2",
+    "@tanstack/react-virtual": "3.11.3",
     "@vercel/analytics": "^1.4.1",
     "canvas-confetti": "^1.9.2",
     "clsx": "^1.2.1",
@@ -136,7 +136,7 @@
     "prettier": "^2.7.1",
     "tailwindcss": "3.4.14",
     "tsx": "^3.8.2",
-    "typescript": "^5.5.0",
+    "typescript": "^5.7.3",
     "uuid": "^8.3.2"
   },
   "pnpm": {

package.json

@@ -133,7 +133,7 @@
     "tsup": "8.3.5",
     "tsx": "^4.19.2",
     "turbo": "1.6.3",
-    "typescript": "^5.5.0",
+    "typescript": "^5.7.3",
     "webpack": "^5.53.0",
     "webpack-bundle-analyzer": "^4.4.2",
     "webpack-cli": "^3.3.11",

packages/components/listbox/package.json

@@ -45,7 +45,7 @@
     "@heroui/react-utils": "workspace:*",
     "@heroui/shared-utils": "workspace:*",
     "@heroui/use-is-mobile": "workspace:*",
-    "@tanstack/react-virtual": "3.11.2",
+    "@tanstack/react-virtual": "3.11.3",
     "@react-aria/utils": "3.27.0",
     "@react-aria/listbox": "3.14.0",
     "@react-stately/list": "3.11.2",

packages/components/select/package.json

@@ -59,7 +59,7 @@
     "@react-aria/utils": "3.27.0",
     "@react-aria/visually-hidden": "3.8.19",
     "@react-types/shared": "3.27.0",
-    "@tanstack/react-virtual": "3.11.2"
+    "@tanstack/react-virtual": "3.11.3"
   },
   "devDependencies": {
     "@heroui/avatar": "workspace:*",

packages/components/table/package.json

@@ -53,7 +53,8 @@
     "@react-stately/table": "3.13.1",
     "@react-stately/virtualizer": "4.2.1",
     "@react-types/grid": "3.2.11",
-    "@react-types/table": "3.10.4"
+    "@react-types/table": "3.10.4",
+    "@tanstack/react-virtual": "3.11.3"
   },
   "devDependencies": {
     "@heroui/theme": "workspace:*",

packages/components/table/src/table-row-group.tsx

@@ -1,4 +1,6 @@
-import {forwardRef, HTMLHeroUIProps} from "@heroui/system";
+import type {HTMLHeroUIProps} from "@heroui/system";
+
+import {forwardRef} from "react";
 import {useDOMRef} from "@heroui/react-utils";
 import {clsx} from "@heroui/shared-utils";
 import {useTableRowGroup} from "@react-aria/table";
@@ -11,10 +13,11 @@ export interface TableRowGroupProps extends HTMLHeroUIProps<"thead"> {
   classNames?: ValuesType["classNames"];
 }
 
-const TableRowGroup = forwardRef<"thead", TableRowGroupProps>((props, ref) => {
+const TableRowGroup = forwardRef<HTMLTableSectionElement, TableRowGroupProps>((props, ref) => {
   const {as, className, children, slots, classNames, ...otherProps} = props;
 
   const Component = as || "thead";
+
   const domRef = useDOMRef(ref);
 
   const {rowGroupProps} = useTableRowGroup();