gridcn2.0.0
Server path

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:

  1. Can the browser hold every row, and can one request load them? Use a local array. For numbered pages, add client pagination.
  2. Does the user jump to numbered pages? Use pages mode (server pagination).
  3. Otherwise, use scroll mode. If the row count passes the row limit, use pages mode instead.

Match the mode to your API

ModeUse it whenYou write
Local arrayThe browser holds every row.data or defaultData
Client paginationThe rows are in memory and the user wants numbered pages.defaultPageSize on the provider
Pages modeYour API returns one page for each request.fetchRows with start and end, or page and pageSize
Scroll mode, random accessYour API reads rows by offset and returns the row count.fetchRows with start and end
Scroll mode, sequential sourceYour 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.

Next: Load server rows.

On this page