gridcn2.0.0
Server pagination

Tune page loading

Page through a cursor API, load the next page early, and refresh the page on a timer with useDataGridServerRows in pages mode.

These options belong to useDataGridServerRows in pages mode. Set them after the pager from Load rows by page works. When the last pending insert or delete settles, the hook loads the page again, unless refreshAfterSave is false.

Page through a cursor API

A keyset API returns a nextCursor and no page numbers. Answer { rows, nextCursor }. The page request carries cursor, the nextCursor of the page before. The hook then treats the source as a cursor source:

  • It stores the cursor of each page it reached, and reuses it for back, forward, refresh(), and retry().
  • It drops the chain when the sort, the filter, the search text, or the page size changes.
  • It shows a pager without a count and without a last page.
  • It moves a page beyond the known chain back to the furthest known page.

nextCursor: null ends the source. Do not keep the chain in your own state.

This grid pages through a cursor API:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { DataGridPaginationBar } from "@/components/data-grid-pagination/data-grid-pagination";
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" },
]);

export function OrdersGrid() {
  const server = useDataGridServerRows<Order, string>({
    fetchRows: async ({ cursor, start, end, signal }) => {
      const query = new URLSearchParams({ limit: String(end - start) });
      if (cursor !== undefined) query.set("after", cursor);
      const response = await fetch(`/api/orders?${query}`, { signal });
      const page = await response.json();
      return { rows: page.items, nextCursor: page.next ?? null };
    },
  });

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

With a fetch library, useInfiniteQuery or useSWRInfinite keeps the chain for you. These demos show scroll mode and a pager over a cursor API and a pager over a cursor API:

0 rows so far, end of the list · fetching…
Name
Email
Role
No rows
0 rows so far, more available · fetching…
Name
Email
Role
No rows

Load the next page early

Set prefetchNextPage to fetch the page after the current one in the background once the current page has landed. The pager then shows that page with no request and no loading state. A failed prefetch is silent. The default is false.

The hook drops a prefetched page in these cases:

  • A refresh, a revalidation tick, a spec change, or a page size change.
  • A local insert, delete, or move, and the start of a save.
  • The user does not reach the page within revalidateIntervalMs, or within 30 seconds without it.

Refresh on a timer

Set revalidateIntervalMs to call refresh() on a timer while the page is visible. Refresh on a timer lists the rules.

On this page