gridcn2.0.0
Scroll mode

Tune row retention

Cap the loaded rows of scroll mode, evict row ranges far from the viewport, and list the rows that are loaded.

Loaded rows stay in the sparse data array, and a long scroll through a large result grows it. Three levers tune the array: maxLoadedRows caps it, evict drops row ranges, and getLoadedRanges lists what is loaded. A spec change, a changed row count, a remount, and a refresh unload rows too.

Cap the loaded rows

Scroll mode keeps at most maxLoadedRows rows loaded (default 10,000). When more are loaded, the hook unloads blocks outside the keep range. A random access source drops the blocks viewed longest ago, and a sequential source drops the blocks furthest from the rendered rows. Rows with an open edit, a pending save, or an unsaved change, and the row under the active cell, stay in data. A random access source stops counting them as loaded, so the next rendered rows fetch their block whole. A sequential source keeps the whole block. Pass maxLoadedRows: Infinity to keep every row.

Evict row ranges

  1. Pick the row ranges to drop. server.getLoadedRanges() lists the loaded ones, merged and sorted. It never triggers a render, so call it in an effect or a handler.
  2. Call server.evict(rowRange) for each row range you want to drop. A row range is a RowRange, { start, end } with an exclusive end. A partial overlap drops the intersection only, and the rest stays loaded.

When the user scrolls back into an evicted row range, the hook fetches the rows again.

server.unloadedCount counts the rows that render as skeleton rows. A sequential source reports its one block of skeleton rows, and an evicted block shows skeleton rows until it reloads.

An eviction policy is your decision. This grid drops the loaded blocks that are at least 500 rows away from the rendered rows. It rounds the edges to multiples of blockSize, so a block that comes back asks for the same rows as before:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import {
  useDataGridServerRows,
} from "@/components/data-grid-server/data-grid-server";

type Order = { id: string; customer: string };

const columns = defineColumns<Order>()([
  { id: "customer", header: "Customer", accessorKey: "customer" },
]);

const BLOCK_SIZE = 50;
const MIN_DISTANCE = 500;

export function OrdersGrid() {
  const server = useDataGridServerRows<Order>({
    mode: "scroll",
    blockSize: BLOCK_SIZE,
    fetchRows: async ({ start, end, signal }) => {
      const query = `offset=${start}&limit=${end - start}`;
      const response = await fetch(`/api/orders?${query}`, { signal });
      const answer = await response.json();
      return { rows: answer.rows, totalRowCount: answer.total };
    },
    onRenderedRowsChange: (range) => {
      const behind = range.start - MIN_DISTANCE;
      const ahead = range.end + MIN_DISTANCE;
      server.evict({
        start: 0,
        end: Math.floor(behind / BLOCK_SIZE) * BLOCK_SIZE,
      });
      server.evict({
        start: Math.ceil(ahead / BLOCK_SIZE) * BLOCK_SIZE,
        end: Number.MAX_SAFE_INTEGER,
      });
    },
  });

  return <DataGrid {...server.gridProps} columns={columns} className="h-96" />;
}

The onRenderedRowsChange option runs after the hook has read the rendered row range, so blocks keep loading.

Two behaviors matter for a policy of your own:

  • evict aborts the requests it covers, and a request that started before the evict drops its answer. It keeps rows with an open edit, a pending save, or an unsaved change, and the row under the active cell.
  • An unsaved change stays in the row until its block loads again. The answer then replaces the unsaved value, because the hook does not save. When an edit targets a row that the hook evicted before the merge, the hook warns once in development. See Load rows while scrolling.

evict clamps the row range to [0, totalRowCount). A sequential source ignores it.

Refresh on a timer

revalidateIntervalMs calls refresh() on a timer. See Refresh on a timer.

Undo and redo compose with the onDataChange of the hook. See Run history with scroll mode.

Limits with server state

The limits, the timer, and evict follow the spec of the hook in every setup:

  • Server sort and filter. The hook sets sortMode="server" and filterMode="server". A sort or filter change starts the blocks over, so no limit holds rows of the old order.
  • Controlled state. Pass spec with onSpecChange to the hook, and the grid follows it. A changed spec drops the loaded rows and aborts the requests in flight.
  • Your own onDataChange. The onDataChange option of the hook runs after the merge. Rows that your handler keeps outside the hook are not covered by maxLoadedRows.

On this page