Load without row count
Load a keyset or "has more" API in scroll mode when the server sends a next cursor and no row count.
A keyset API gives a next cursor and no row count. Scroll mode loads such a source one block at a time, and each request carries the cursor of the block before it. The grid shows the loaded rows plus one block of skeleton rows, so the scroll height grows in steps.
Load a cursor chain
- Pass the cursor type as the second type argument of
useDataGridServerRows. - Send
cursorto your API. The first call getscursor: undefined. - Resolve
fetchRowswith{ rows, nextCursor }. ReturnnextCursor: nullafter the last row.
This grid loads orders after a cursor:
"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" },
]);
export function OrdersGrid() {
const server = useDataGridServerRows<Order, string>({
mode: "scroll",
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" />;
}A first answer with nextCursor, or with neither totalRowCount nor nextCursor, starts a sequential source. fetchRows returns at most end - start rows. The hook keeps the first end - start rows of a longer answer. In a cursor chain, the rows past end - start are lost, because the next cursor moves past them. So send end - start as the page size.
When the source ends
nextCursor: nullends the source. Any other value means more rows exist and comes back ascursor. A value of0counts as a cursor.- An API with a "has more" flag and no cursor answers
{ rows, hasMore }. The request still asks for[start, end), andstartfollows the rows received so far.hasMore: falseends the source. - Without a cursor and without the flag, a block that comes back full means more rows exist.
- A
totalRowCountthat comes with a cursor caps the skeleton rows. When the loaded rows reach it, the source ends. - An empty block ends the source. A cursor that repeats the one the request sent, or one that came back before, ends the source with a warning in development.
- The source stops at 10,000,000 loaded rows.
At the end the skeleton rows go away and totalRowCount holds the final row count.
Force the fetch order
The first answer picks the order. To force it, pass source: "random" for random access or source: "sequential" for a sequential source. A random source that answers without totalRowCount warns in development.
How the source advances
When the rendered rows come within overscan rows of the loaded end, the next block starts. overscan is 30 by default. One block loads at a time.
- A failed block sets
error, callsonError, and stops the source.retry()repeats the block, and so does the next report of the rendered rows. - A change of the sort, filter, or search text drops the loaded rows and the cursor. The source starts again at block 0.
refresh()fetches again from the first block and keeps the loaded rows on screen until the answers land.evictdoes nothing on a sequential source, because it cannot refetch an arbitrary range.maxLoadedRows(default 10,000) unloads the blocks furthest from the rendered rows. The hook stores the cursor that each block was requested with. When the user scrolls back, it sends that request again, sofetchRowsmust answer the same cursor with the same rows. PassmaxLoadedRows: Infinityto keep every loaded row until a spec change or arefresh().
Select rows without a row count
While the server sends no count, totalRowCount is null. The header checkbox then checks all matching, the loaded rows and the rows that are not loaded yet. server.gridProps carries totalRowCount: null until the source ends. The grid remembers checks by row id and offers actions.selectAllMatching(). See Select server rows.
Related
- Load rows while scrolling: the source with a row count
- Recover from load errors: a block that fails
- Server rows options:
nextCursorandhasMore - Load rows by page: paging without a total