gridcn2.0.0
Add-on optionsRows, pages, and menus

Client pagination options

Look up the options and result of useDataGridPagination, the props of DataGridPaginationBar, and the parts you compose into a custom footer.

A grid pages its view with pageSize or defaultPageSize on DataGridProvider. DataGridPaginationBar renders the footer from the pager of the grid. useDataGridPagination pages a list that is not a grid. The behavior, how sort, filter, and search cover every page, and the install steps are on Client pagination.

SymbolPurposeGuide
useDataGridPagerReturns the pager of a grid that pages its viewClient pagination
DataGridPaginationBarRenders the footerClient pagination
Footer partsCompose a custom footerClient pagination
useDataGridServerPagerReturns the pager of rows that you fetch yourselfLoad rows by page
useDataGridPaginationPages a list that is not a gridClient pagination

Grid pager

This sample pages a grid with 25 rows to a page:

import {
  DataGridBody,
  DataGridHeader,
  DataGridProvider,
  DataGridRoot,
  defineColumns,
} from "@/components/data-grid/data-grid";
import {
  DataGridPaginationBar,
} from "@/components/data-grid-pagination/data-grid-pagination";

type Person = { id: string; name: string };

const columns = defineColumns<Person>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

export function PagedGrid({ rows }: { rows: Person[] }) {
  return (
    <DataGridProvider defaultData={rows} columns={columns} defaultPageSize={25}>
      <DataGridRoot className="h-96">
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
      <DataGridPaginationBar />
    </DataGridProvider>
  );
}

useDataGridPager({ pageSizeOptions }) returns { pager } for a grid that pages its view. Call it under DataGridProvider. DataGridPaginationBar with no props calls it for you. Inside a server grid, the bar reads the pager from useDataGridServerRows or from gridProps of useDataGridServerPager. Its options type is UseDataGridPagerOptions. A grid without pageSize reads as one page that holds every row, so the bar shows one page.

DataGridPaginationBar

Spread the pager onto the bar. Inside a paged DataGridProvider, pass no pager and the bar reads the grid.

Prop

Type

The root element carries the data-grid-pagination attribute. labels merges over the labels.pagination of the enclosing grid, or over the labels.pagination defaults outside a DataGridProvider.

Footer parts

Without children, the bar renders the range, the page-size select, and the first, previous, pages, next, and last controls. Pass children to arrange the parts yourself. Every part reads the pager from the bar. A part outside a bar throws.

PartRenders
DataGridPaginationRangeThe range label, the empty label, or "Page 3" when the count is null
DataGridPaginationPageSizeThe rows-per-page select
DataGridPaginationFirstA button to page 1, disabled on page 1
DataGridPaginationPrevA button to the previous page, disabled on page 1
DataGridPaginationPagesThe numbered buttons, windowSize at a time (default 5). The props type is DataGridPaginationPagesProps.
DataGridPaginationNextA button to the next page, disabled without a next page
DataGridPaginationLastA button to the last page, disabled on the last page and while the count is unknown

This sample builds a compact footer for a list:

import {
  DataGridPaginationBar,
  DataGridPaginationNext,
  DataGridPaginationPrev,
  DataGridPaginationRange,
  useDataGridPagination,
} from "@/components/data-grid-pagination/data-grid-pagination";

export function CompactPager({ rows }: { rows: { id: string }[] }) {
  const { pageData, pager } = useDataGridPagination({
    data: rows,
    defaultPageSize: 25,
  });
  return (
    <>
      <p>{pageData.length} rows on this page</p>
      <DataGridPaginationBar {...pager}>
        <DataGridPaginationRange />
        <div className="flex items-center gap-1">
          <DataGridPaginationPrev />
          <DataGridPaginationNext />
        </div>
      </DataGridPaginationBar>
    </>
  );
}

Server pager

useDataGridServerPager returns { pager, gridProps } for rows that you fetch yourself. Its options are on Server rows options.

useDataGridPagination

The hook slices data into pages for a list that is not a grid. To page a grid, set pageSize or defaultPageSize on DataGridProvider.

Prop

Type

pageSizeOptions defaults to [10, 25, 50, 100]. DataGridProvider takes pageSizeOptions too. The bar and useDataGridPager read it, and an option on the bar or the hook wins. Without defaultPageSize, the first size of pageSizeOptions applies. The page and the page size stay uncontrolled until you pass page or pageSize. A page-size change moves to the page that holds the first row of the current page.

Result

Prop

Type

pageData holds the rows of the current page. The pager has one shape for every source of pages:

Prop

Type

On this page