fix(Table): table rerenders

README.md

@@ -561,6 +561,36 @@ const TableSettingsDemo = () => {
 
 Learn more about the table and the column resizing properties in the react-table [docs](https://tanstack.com/table/v8/docs/api/features/column-sizing)
 
+## Memoization (experimental)
+
+Pass `experimentalMemoization` on `Table` / `BaseTable` to enable
+`React.memo` on rows and cells. This avoids re-rendering every row and cell
+when one row's state changes. The flag is opt-in; without it the rendering
+behavior is unchanged.
+
+```tsx
+<Table table={table} experimentalMemoization />
+```
+
+By default, the memo comparator tracks `row.getIsSelected()` and
+`row.getIsExpanded()`. If your custom cells read other row state (or external
+state keyed by row id), declare it via `getRowVersion`:
+
+```tsx
+const getRowVersion = (row: Row<MyData>) =>
+  [row.getIsSelected(), row.getIsExpanded(), row.getIsPinned()] as const;
+
+<Table table={table} experimentalMemoization getRowVersion={getRowVersion} />;
+```
+
+`getRowVersion` is called once per row per parent render. Returned values are
+compared element-wise with `Object.is` — any change invalidates the row's memo
+and re-renders only that row's cells.
+
+See [`docs/MIGRATION-experimentalMemoization.md`](docs/MIGRATION-experimentalMemoization.md)
+for anti-patterns that defeat memoization, the verification recipe, and a
+worked migration example.
+
 ## Known Issues and Compatibility
 
 ### React 19 + React Compiler Compatibility

src/components/BaseCell/BaseCell.memo.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react';
+
+import {arraysShallowEqual} from '../../utils';
+
+import type {BaseCellProps} from './BaseCell';
+import {BaseCell} from './BaseCell';
+
+function areCellPropsEqual<TData>(prev: BaseCellProps<TData>, next: BaseCellProps<TData>): boolean {
+    return (
+        arraysShallowEqual(prev._rowVersion ?? [], next._rowVersion ?? []) &&
+        prev.cell === next.cell &&
+        prev.className === next.className &&
+        prev.attributes === next.attributes &&
+        prev.style === next.style &&
+        prev.children === next.children &&
+        prev.colSpan === next.colSpan &&
+        prev['aria-colindex'] === next['aria-colindex']
+    );
+}
+
+export const MemoBaseCell = React.memo(BaseCell, areCellPropsEqual) as typeof BaseCell;

src/components/BaseCell/BaseCell.tsx

@@ -13,6 +13,7 @@ export interface BaseCellProps<TData>
     attributes?:
         | React.TdHTMLAttributes<HTMLTableCellElement>
         | ((cell?: Cell<TData, unknown>) => React.TdHTMLAttributes<HTMLTableCellElement>);
+    _rowVersion?: readonly unknown[];
 }
 
 export const BaseCell = <TData,>({
@@ -21,6 +22,7 @@ export const BaseCell = <TData,>({
     className: classNameProp,
     style,
     attributes: attributesProp,
+    _rowVersion: _rowVersionDiscarded,
     ...restProps
 }: BaseCellProps<TData>) => {
     const attributes = typeof attributesProp === 'function' ? attributesProp(cell) : attributesProp;

src/components/BaseCell/index.ts

@@ -1 +1,2 @@
 export * from './BaseCell';
+export * from './BaseCell.memo';

src/components/BaseDraggableRow/BaseDraggableRow.memo.tsx

@@ -0,0 +1,62 @@
+import * as React from 'react';
+
+import {arraysShallowEqual} from '../../utils';
+import {MemoBaseCell} from '../BaseCell/BaseCell.memo';
+
+import {BaseDraggableRow} from './BaseDraggableRow';
+import type {BaseDraggableRowProps} from './BaseDraggableRow';
+
+export interface MemoBaseDraggableRowProps<
+    TData,
+    TScrollElement extends Element | Window = HTMLDivElement,
+> extends BaseDraggableRowProps<TData, TScrollElement> {
+    _rowVersion: readonly unknown[];
+}
+
+// eslint-disable-next-line complexity
+function areEqual<TData, TScrollElement extends Element | Window>(
+    prev: Readonly<BaseDraggableRowProps<TData, TScrollElement>>,
+    next: Readonly<BaseDraggableRowProps<TData, TScrollElement>>,
+): boolean {
+    return (
+        prev.row === next.row &&
+        arraysShallowEqual(prev._rowVersion ?? [], next._rowVersion ?? []) &&
+        prev.table === next.table &&
+        prev.virtualItem?.start === next.virtualItem?.start &&
+        prev.virtualItem?.size === next.virtualItem?.size &&
+        prev.style === next.style &&
+        prev.cellClassName === next.cellClassName &&
+        prev.className === next.className &&
+        prev.onClick === next.onClick &&
+        prev.getIsCustomRow === next.getIsCustomRow &&
+        prev.getIsGroupHeaderRow === next.getIsGroupHeaderRow &&
+        prev.renderCustomRowContent === next.renderCustomRowContent &&
+        prev.renderGroupHeader === next.renderGroupHeader &&
+        prev.renderGroupHeaderRowContent === next.renderGroupHeaderRowContent &&
+        prev.getGroupTitle === next.getGroupTitle &&
+        prev.groupHeaderClassName === next.groupHeaderClassName &&
+        prev.attributes === next.attributes &&
+        prev.cellAttributes === next.cellAttributes &&
+        prev.rowVirtualizer === next.rowVirtualizer &&
+        prev['aria-rowindex'] === next['aria-rowindex'] &&
+        prev['aria-selected'] === next['aria-selected']
+    );
+}
+
+const BaseDraggableRowWithMemoCell = React.forwardRef(function BaseDraggableRowWithMemoCellRender<
+    TData,
+    TScrollElement extends Element | Window,
+>(props: BaseDraggableRowProps<TData, TScrollElement>, ref: React.Ref<HTMLTableRowElement>) {
+    return <BaseDraggableRow {...props} Cell={MemoBaseCell} ref={ref} />;
+}) as <TData, TScrollElement extends Element | Window = HTMLDivElement>(
+    props: BaseDraggableRowProps<TData, TScrollElement> & {ref?: React.Ref<HTMLTableRowElement>},
+) => React.ReactElement;
+
+export const MemoBaseDraggableRow = React.memo(BaseDraggableRowWithMemoCell, areEqual) as <
+    TData,
+    TScrollElement extends Element | Window = HTMLDivElement,
+>(
+    props: MemoBaseDraggableRowProps<TData, TScrollElement> & {
+        ref?: React.Ref<HTMLTableRowElement>;
+    },
+) => React.ReactElement;

src/components/BaseDraggableRow/index.ts

@@ -1 +1,2 @@
 export * from './BaseDraggableRow';
+export * from './BaseDraggableRow.memo';

src/components/BaseGroupHeader/BaseGroupHeader.tsx

@@ -1,4 +1,4 @@
-import type * as React from 'react';
+import * as React from 'react';
 
 import type {Row} from '@tanstack/react-table';
 
@@ -17,11 +17,13 @@ export const BaseGroupHeader = <TData,>({
     className,
     getGroupTitle,
 }: BaseGroupHeaderProps<TData>) => {
+    const isExpanded = row.getIsExpanded();
+
     return (
         <h2 className={b(null, className)}>
             <button className={b('button')} onClick={row.getToggleExpandedHandler()}>
                 <svg
-                    className={b('icon', {expanded: row.getIsExpanded()})}
+                    className={b('icon', {expanded: isExpanded})}
                     viewBox="0 0 16 16"
                     width="16"
                     height="16"

src/components/BaseRow/BaseRow.memo.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+
+import {arraysShallowEqual} from '../../utils';
+import {MemoBaseCell} from '../BaseCell/BaseCell.memo';
+
+import type {BaseRowProps} from './BaseRow';
+import {BaseRow} from './BaseRow';
+
+export interface MemoBaseRowProps<TData, TScrollElement extends Element | Window = HTMLDivElement>
+    extends BaseRowProps<TData, TScrollElement> {
+    _rowVersion: readonly unknown[];
+}
+
+// eslint-disable-next-line complexity
+function areEqual<TData, TScrollElement extends Element | Window>(
+    prev: Readonly<BaseRowProps<TData, TScrollElement>>,
+    next: Readonly<BaseRowProps<TData, TScrollElement>>,
+): boolean {
+    return (
+        prev.row === next.row &&
+        arraysShallowEqual(prev._rowVersion ?? [], next._rowVersion ?? []) &&
+        prev.table === next.table &&
+        prev.virtualItem?.start === next.virtualItem?.start &&
+        prev.virtualItem?.size === next.virtualItem?.size &&
+        prev.style === next.style &&
+        prev.cellClassName === next.cellClassName &&
+        prev.className === next.className &&
+        prev.onClick === next.onClick &&
+        prev.getIsCustomRow === next.getIsCustomRow &&
+        prev.getIsGroupHeaderRow === next.getIsGroupHeaderRow &&
+        prev.renderCustomRowContent === next.renderCustomRowContent &&
+        prev.renderGroupHeader === next.renderGroupHeader &&
+        prev.renderGroupHeaderRowContent === next.renderGroupHeaderRowContent &&
+        prev.getGroupTitle === next.getGroupTitle &&
+        prev.groupHeaderClassName === next.groupHeaderClassName &&
+        prev.attributes === next.attributes &&
+        prev.cellAttributes === next.cellAttributes &&
+        prev.rowVirtualizer === next.rowVirtualizer &&
+        prev['aria-selected'] === next['aria-selected']
+    );
+}
+
+const BaseRowWithMemoCell = React.forwardRef(function BaseRowWithMemoCellRender<
+    TData,
+    TScrollElement extends Element | Window,
+>(props: BaseRowProps<TData, TScrollElement>, ref: React.Ref<HTMLTableRowElement>) {
+    return <BaseRow {...props} Cell={MemoBaseCell} ref={ref} />;
+}) as <TData, TScrollElement extends Element | Window = HTMLDivElement>(
+    props: BaseRowProps<TData, TScrollElement> & {ref?: React.Ref<HTMLTableRowElement>},
+) => React.ReactElement;
+
+export const MemoBaseRow = React.memo(BaseRowWithMemoCell, areEqual) as <
+    TData,
+    TScrollElement extends Element | Window = HTMLDivElement,
+>(
+    props: MemoBaseRowProps<TData, TScrollElement> & {ref?: React.Ref<HTMLTableRowElement>},
+) => React.ReactElement;

src/components/BaseRow/BaseRow.tsx

@@ -40,6 +40,8 @@ export interface BaseRowProps<TData, TScrollElement extends Element | Window = H
         | React.HTMLAttributes<HTMLTableRowElement>
         | ((row: Row<TData>) => React.HTMLAttributes<HTMLTableRowElement>);
     cellAttributes?: BaseCellProps<TData>['attributes'];
+    Cell?: React.FunctionComponent<BaseCellProps<TData>>;
+    _rowVersion?: readonly unknown[];
 }
 
 export const BaseRow = React.forwardRef(
@@ -61,13 +63,17 @@ export const BaseRow = React.forwardRef(
             virtualItem,
             attributes: attributesProp,
             cellAttributes,
+            Cell = BaseCell,
             table: _,
+            _rowVersion,
             ...restProps
         }: BaseRowProps<TData, TScrollElement>,
         ref: React.Ref<HTMLTableRowElement>,
     ) => {
         const rowRef = useForkRef(rowVirtualizer?.measureElement, ref);
 
+        const isSelected = row.getIsSelected();
+
         const attributes =
             typeof attributesProp === 'function' ? attributesProp(row) : attributesProp;
 
@@ -96,11 +102,12 @@ export const BaseRow = React.forwardRef(
                         getGroupTitle,
                     })
                 ) : (
-                    <BaseCell
+                    <Cell
                         className={cellClassName}
                         colSpan={row.getVisibleCells().length}
                         attributes={cellAttributes}
                         aria-colindex={1}
+                        _rowVersion={_rowVersion}
                     >
                         {renderGroupHeader ? (
                             renderGroupHeader({
@@ -115,7 +122,7 @@ export const BaseRow = React.forwardRef(
                                 getGroupTitle={getGroupTitle}
                             />
                         )}
-                    </BaseCell>
+                    </Cell>
                 );
             }
 
@@ -126,12 +133,13 @@ export const BaseRow = React.forwardRef(
             return row
                 .getVisibleCells()
                 .map((cell) => (
-                    <BaseCell
+                    <Cell
                         key={cell.id}
                         cell={cell}
                         className={cellClassName}
                         attributes={cellAttributes}
                         aria-colindex={cell.column.getIndex() + 1}
+                        _rowVersion={_rowVersion}
                     />
                 ));
         };
@@ -142,7 +150,7 @@ export const BaseRow = React.forwardRef(
                 className={b(
                     'row',
                     {
-                        selected: row.getIsSelected(),
+                        selected: isSelected,
                         interactive: Boolean(onClick),
                     },
                     className,