Lazy loading

data-grid-lazy gives the grid a total and a fetchRows(start, end) function, and useDataGridLazyRows fetches whatever range the grid actually scrolls into.

pnpm dlx shadcn@latest add @gridcn/data-grid-lazy

Lazy loading gives an infinite-feel single scrollable surface: no page boundary, a grid that fills in as the user scrolls. It fits one continuous dataset best. Explicit, bookmarkable pages with a bounded per-request payload are Pagination. Virtualization renders huge datasets cheaply either way. Neither add-on exists for rendering performance. Using both together is not supported.

Every unloaded-row skeleton cell carries data-skeleton (see Data-attribute contract), for restyling the shimmer with plain CSS instead of a class override.

"use client";

import {
  DataGridProvider,
  DataGridRoot,
  DataGridHeader,
  DataGridBody,
} from "@/components/data-grid/data-grid";
import { useDataGridLazyRows, DataGridLazyGuard } from "@/components/data-grid-lazy/data-grid-lazy";

function OrdersGrid({ total }: { total: number }) {
  const lazy = useDataGridLazyRows<Order>({
    total,
    fetchRows: (start, end, signal) => api.orders({ start, end, signal }), // inclusive-exclusive
    getRowId: (row) => row.id,
  });

  return (
    <DataGridProvider
      data={lazy.gridProps.data}
      columns={columns}
      getRowId={lazy.gridProps.getRowId}
      onDataChange={lazy.onDataChange}
      onRenderedRowsChange={lazy.gridProps.onRenderedRowsChange}
    >
      <DataGridLazyGuard hasHoles={lazy.unloadedCount > 0} />
      <DataGridRoot loading={lazy.isLoading}>
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
    </DataGridProvider>
  );
}

const { data: total } = useQuery({ queryKey: ["orders-count"], queryFn: api.orderCount });

return total === undefined ? <Spinner /> : <OrdersGrid total={total} />;

useDataGridLazyRows({
  total,
  fetchRows,
  getRowId,
  onError: (error, range) => toast.error(`Failed to load rows ${range.start}–${range.end}`),
});

Tuning the fetch range

overscan, batchSize, and maxFetchRows control the size of the ranges that reach fetchRows:

• overscan pads the visible range on both sides (default about one viewport of rows).
• batchSize rounds both edges of the padded range outward to the nearest multiple, so a small scroll reuses the same batch.
• maxFetchRows caps the rows of one fetchRows call. A wider gap splits into consecutive chunks of at most the cap. The default is no cap.

overscan and batchSize default to values that fit a typical viewport. maxFetchRows has no default cap. Adjust them when the defaults do not fit:

useDataGridLazyRows({
  total,
  fetchRows,
  getRowId,
  overscan: 60,
  batchSize: 100,
  maxFetchRows: 200,
});

Set maxFetchRows when your backend limits rows per request. Each chunk is an independent request with its own dedup, abort, and failure, and chunk boundaries follow the gap's start, not batchSize boundaries.

Memory & retention

Loaded rows stay in the sparse array until a total change, a remount, or an explicit call removes them:

• lazy.reset() aborts every in-flight fetch and drops all loaded rows. It is the same reset a total change performs. It also re-requests the last reported range, so the visible rows refetch instead of sitting as skeletons. Use it when the dataset behind the same total is invalidated in place, for example after a server-side refresh.
• lazy.evict(range) drops the loaded rows inside range. A partial overlap drops the intersection only, and the rest stays loaded. Evicted rows refetch on the next scroll into them.
• lazy.getLoadedRanges() returns the loaded ranges, merged and sorted. The result never triggers a render. Call it in effects or event handlers.

An eviction policy is a consumer decision. A distance from the visible range is a starting point:

const MIN_DISTANCE = 500;

<DataGridProvider
  data={lazy.gridProps.data}
  columns={columns}
  getRowId={lazy.gridProps.getRowId}
  onRenderedRowsChange={(range) => {
    lazy.gridProps.onRenderedRowsChange(range);
    for (const loaded of lazy.getLoadedRanges()) {
      if (range.start - loaded.end > MIN_DISTANCE || loaded.start - range.end > MIN_DISTANCE) {
        lazy.evict(loaded);
      }
    }
  }}
>
  <DataGridRoot>
    <DataGridHeader />
    <DataGridBody />
  </DataGridRoot>
</DataGridProvider>

The demo's "Evict loaded rows" button runs lazy.evict over the whole range, so every loaded row becomes a skeleton and refetches on scroll.

Two behaviors matter when you wire your own policy:

• An in-flight fetch that started before the evict still lands and marks its range loaded. The evicted rows reappear once that fetch resolves.
• Evicted rows lose edits merged through onDataChange that you did not persist. This hook does not own persistence. See Editing loaded rows.

Undo and redo compose with this hook's onDataChange. The wiring, the hole-tolerant getRowId, and the clear()-on-reset() rule are on the Undo & redo page.

Sorting a lazy grid

The sort must run on the server. Set sortMode="server": the grid tracks the sort spec (the asc → desc → none header cycle, aria-sort, the sort indicator, DataGridSortList) and calls onSortChange, but never reorders data. Hold the spec in your own state and send it to fetchRows:

const [sorts, setSorts] = useState<SortSpec[]>([]);

const lazy = useDataGridLazyRows<Order>({
  total: 100_000,
  getRowId: (row) => row.id,
  fetchRows: (start, end, signal) => api.orders({ start, end, sorts, signal }),
});

const onSortChange = (next: SortSpec[]) => {
  // a sort change invalidates every fetched range, so drop them before the refetch runs
  lazy.reset();
  setSorts(next);
};

<DataGridProvider
  data={lazy.gridProps.data}
  getRowId={lazy.gridProps.getRowId}
  onDataChange={lazy.onDataChange}
  sortMode="server"
  onSortChange={onSortChange}
  headerClickBehavior="sort"
>

Three details make this work:

• sortMode="server" leaves the order to the server. Passing sortState={sorts} as well is allowed: the spec shows in the headers, and the fetched rows keep the order the server sent.
• A header click sorts only with headerClickBehavior="sort". The default, "select", selects the column and never calls onSortChange.
• A sort change discards loaded rows. Already-fetched ranges hold the old order, so onSortChange calls lazy.reset() before the refetch runs. Remounting the provider on a key derived from the spec clears them too. It also resets the core store (selection, edit state, scroll position), so it is the heavier alternative.

Use lazy.isLoading to show a busy state while the refetch is in flight, for example to dim the grid.

Filtering follows the same rule for the same reason: filterState narrows data locally when set. searchText never narrows anything. It only highlights and navigates matches over the rows already in data, so a search over a partial array highlights matches in the loaded part and nothing more.