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",

packages/components/table/package.json

@@ -53,7 +53,8 @@
     "@react-stately/table": "3.13.0",
     "@react-stately/virtualizer": "4.2.0",
     "@react-types/grid": "3.2.10",
-    "@react-types/table": "3.10.3"
+    "@react-types/table": "3.10.3",
+    "@tanstack/react-virtual": "3.11.2"
   },
   "devDependencies": {
     "@heroui/theme": "workspace:*",

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

@@ -11,7 +11,7 @@ export interface TableRowGroupProps extends HTMLHeroUIProps<"thead"> {
   classNames?: ValuesType["classNames"];
 }
 
-const TableRowGroup = forwardRef<"thead", TableRowGroupProps>((props, ref) => {
+const TableRowGroup = forwardRef<any, TableRowGroupProps>((props, ref) => {
   const {as, className, children, slots, classNames, ...otherProps} = props;
 
   const Component = as || "thead";

packages/components/table/src/table.tsx

@@ -3,13 +3,19 @@ import {Spacer} from "@heroui/spacer";
 import {forwardRef} from "@heroui/system";
 
 import {UseTableProps, useTable} from "./use-table";
+import VirtualizedTable from "./virtualized-table";
 import TableRowGroup from "./table-row-group";
 import TableHeaderRow from "./table-header-row";
 import TableColumnHeader from "./table-column-header";
 import TableSelectAllCheckbox from "./table-select-all-checkbox";
 import TableBody from "./table-body";
 
-export interface TableProps extends Omit<UseTableProps, "isSelectable" | "isMultiSelectable"> {}
+export interface TableProps<T = object>
+  extends Omit<UseTableProps<T>, "isSelectable" | "isMultiSelectable"> {
+  isVirtualized?: boolean;
+  rowHeight?: number;
+  maxTableHeight?: number;
+}
 
 const Table = forwardRef<"table", TableProps>((props, ref) => {
   const {
@@ -30,6 +36,10 @@ const Table = forwardRef<"table", TableProps>((props, ref) => {
     ref,
   });
 
+  const {isVirtualized, rowHeight = 40, maxTableHeight = 600} = props;
+
+  const shouldVirtualize = values.collection.size > 50 || isVirtualized;
+
   const Wrapper = useCallback(
     ({children}: {children: JSX.Element}) => {
       if (removeWrapper) {
@@ -41,6 +51,17 @@ const Table = forwardRef<"table", TableProps>((props, ref) => {
     [removeWrapper, getWrapperProps],
   );
 
+  if (shouldVirtualize) {
+    return (
+      <VirtualizedTable
+        {...(props as TableProps)}
+        ref={ref}
+        maxTableHeight={maxTableHeight}
+        rowHeight={rowHeight}
+      />
+    );
+  }
+
   return (
     <div {...getBaseProps()}>
       {topContentPlacement === "outside" && topContent}