Pagination

Client mode

useDataGridPagination slices data into pages itself. Page state is uncontrolled unless you pass page and onPageChange yourself:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridPagination, DataGridPaginationBar } from "@/components/data-grid-pagination/data-grid-pagination";

function OrdersGrid({ rows }: { rows: Order[] }) {
  const pager = useDataGridPagination({ data: rows, pageSize: 25 });

  return (
    <>
      <DataGrid data={pager.pageData} columns={columns} getRowId={(row) => row.id} />
      <DataGridPaginationBar {...pager.controls} />
    </>
  );
}

pageSize seeds the page size once; pass onPageSizeChange to observe a change from the bar's select.

const onDataChange = useCallback((next: readonly DemoRow[]) => {
  setRows((prev) => {
    const edited = new Map(next.map((row) => [row.id, row]));
    return prev.map((row) => edited.get(row.id) ?? row);
  });
}, []);

Server mode

Pass { page, pageSize, total, onPageChange } fully controlled. You own the page index and fetch each page's rows yourself. The hook only computes pageCount and page-window math, so <DataGridPaginationBar /> renders identically either way:

"use client";

import { useEffect, useState } from "react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
import { useDataGridPagination, DataGridPaginationBar } from "@/components/data-grid-pagination/data-grid-pagination";

function OrdersGrid() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(25);
  const [rows, setRows] = useState<Order[]>([]);
  const [total, setTotal] = useState(0);

  useEffect(() => {
    // Guard against stale responses: a page-2 answer arriving after page-3's request
    // must not overwrite page-3's rows (fast page clicks race the network).
    let stale = false;
    api.orders({ page, pageSize }).then((res) => {
      if (stale) return;
      setRows(res.rows);
      setTotal(res.total);
    });
    return () => { stale = true; };
  }, [page, pageSize]);

  const pager = useDataGridPagination({
    page,
    pageSize,
    total,
    onPageChange: setPage,
    onPageSizeChange: setPageSize,
  });

  return (
    <>
      <DataGrid data={rows} columns={columns} getRowId={(row) => row.id} />
      <DataGridPaginationBar {...pager.controls} />
    </>
  );
}

pager.pageData is undefined in server mode. You already fetched exactly the rows for the current page, so there is nothing left for the hook to slice.

The bar clamps the displayed page when total shrinks below it, but your page state is yours. If a stale page would fetch the wrong rows, pass reconcilePage: true. The hook then fires your onPageChange with the clamped page once. The hook never sets your state. While total is 0 (your first fetch is still in flight), the hook keeps your page, so a deep link survives until the total arrives.

<DataGridPaginationBar />

The default footer has:

• First and prev buttons.
• A sliding set of page-number buttons (5 at a time by default, sliding to stay centered on the current page; the bar's windowSize prop changes the count).
• Next and last buttons.
• A page-size <Select>.
• An "x-y of z" range label.

It is a standalone component. It does not read from the store of DataGridProvider, since client-mode pagination has nothing to do with sort, filter, or selection state, so it works whether you render it inside or outside the provider. All strings route through the labels.pagination group (see i18n). Pass a labels prop directly on <DataGridPaginationBar> to override them.

The root <div> also carries [data-grid-pagination], for CSS that targets the footer without a className (see Data-attribute contract).

Composition

DataGridPaginationBar renders its default layout only when given no children. Pass children built from the parts below for a custom arrangement, for example a compact bar with only first, prev, next, and last, and no page numbers:

<DataGridPaginationBar {...pager.controls}>
  <DataGridPaginationRange />
  <div className="flex items-center gap-1">
    <DataGridPaginationFirst />
    <DataGridPaginationPrev />
    <DataGridPaginationNext />
    <DataGridPaginationLast />
  </div>
</DataGridPaginationBar>

Every part reads the bar's controls and labels through context, so none of them take the pagination props directly. Only DataGridPaginationBar does. Each part throws if rendered outside a DataGridPaginationBar.

• DataGridPaginationRange: the "x-y of z" label.
• DataGridPaginationPageSize: the rows-per-page <Select>.
• DataGridPaginationFirst / DataGridPaginationLast: jump to page 1 or the last page. Disabled at their respective edge.
• DataGridPaginationPrev / DataGridPaginationNext: moves the page by 1, chevron-only. Disabled at their respective edge.
• DataGridPaginationPages: the sliding numbered page buttons, the only source of page numbers. Takes an optional windowSize prop (default 5).