Compare data modes
Step 1 of 5
Pick the data mode that fits your rows, from a local array to server pages or scroll mode, and see what each mode needs from your API.
Before you start, render your first grid from a local array. This step is the first of the server path. It ends with one choice: the data mode of your grid.
A data mode is one way the grid gets its rows. Ask these questions in order and stop at the first yes:
- Can the browser hold every row, and can one request load them? Use a local array. For numbered pages, add client pagination.
- Does the user jump to numbered pages? Use pages mode (server pagination).
- Otherwise, use scroll mode. If the row count passes the row limit, use pages mode instead.
Match the mode to your API
| Mode | Use it when | You write |
|---|---|---|
| Local array | The browser holds every row. | data or defaultData |
| Client pagination | The rows are in memory and the user wants numbered pages. | defaultPageSize on the provider |
| Pages mode | Your API returns one page for each request. | fetchRows with start and end, or page and pageSize |
| Scroll mode, random access | Your API reads rows by offset and returns the row count. | fetchRows with start and end |
| Scroll mode, sequential source | Your API returns a next cursor and no row count. | fetchRows with cursor |
With a local array, the grid sorts, filters, and searches data itself. With a server mode, your API does that work and the grid shows the answer. The server hook sets sortMode="server" and filterMode="server" for you.
The browser limits how many rows one grid scrolls. See Row limits. A result above that limit needs pages mode, because a scroll mode source with a row count shows every row in one list.
By default, scroll mode picks random access or a sequential source from the first answer. Set source: "random" or source: "sequential" to fix the choice. An answer with totalRowCount and no nextCursor field gives random access. Any other first answer gives a sequential source.
See the difference in code
A local array needs no hook. A server mode needs useDataGridServerRows. This sample uses pages mode:
"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 LocalOrders({ rows }: { rows: Order[] }) {
return <DataGrid defaultData={rows} columns={columns} className="h-96" />;
}
export function ServerOrders() {
const server = useDataGridServerRows<Order>({
fetchRows: async ({ spec, start, end, signal }) => {
const response = await fetch("/api/orders/query", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ spec, start, end }),
signal,
});
const answer = await response.json();
return { rows: answer.rows, totalRowCount: answer.total };
},
});
return (
<>
<DataGrid {...server.gridProps} columns={columns} className="h-96" />
<DataGridPaginationBar {...server.pager} />
</>
);
}Without mode, the hook runs in pages mode and needs a pager. With mode: "scroll", leave the pager out. The hook fixes its mode for its whole life. To switch, put the hook and the grid in one component, and remount that component with a key.
Result
You know which mode fits your rows. The next step writes a loadPage function and adds a pager.
- To skip the server path, go to Where next.
- For pages mode, go on to the next step.
- For scroll mode, read Load rows while scrolling, keep your own
fetchRows, leave out the pager, and continue with Plan server saves.
Next: Load server rows.