gridcn2.0.0
Rows, pages, and menus

Client pagination

Split a local array into pages with a pager footer, and learn what sort, filter, search, edits, and selection do on a page.

A pager gives the user a numbered page, a page size, and a "21-40 of 240" label. Set defaultPageSize on DataGridProvider to page the view of a local array, and render DataGridPaginationBar as the footer. If your server returns one page per request, see Load rows by page.

Name
Email
Role
Score
Silent Tiger
user0@example.com
Viewer
4
Quick Lion
user1@example.com
Viewer
89
Swift Wolf
user2@example.com
Manager
80
Eager Lion
user3@example.com
User
51
Eager Tiger
user4@example.com
Viewer
83
Silent Wolf
user5@example.com
User
15
Swift Lion
user6@example.com
Viewer
62
Eager Lion
user7@example.com
Manager
42
Eager Eagle
user8@example.com
Editor
35
Bold Tiger
user9@example.com
Editor
52
Bold Bear
user10@example.com
User
28
Swift Wolf
user11@example.com
Manager
9
Swift Bear
user12@example.com
Viewer
45
Eager Wolf
user13@example.com
Editor
44
Swift Eagle
user14@example.com
Viewer
51
Quick Lion
user15@example.com
Manager
28
Bold Wolf
user16@example.com
Editor
76
Swift Eagle
user17@example.com
Admin
26
Eager Eagle
user18@example.com
Manager
70
Eager Bear
user19@example.com
Editor
67
Silent Lion
user20@example.com
Manager
89
Silent Tiger
user21@example.com
Manager
40
Eager Tiger
user22@example.com
Manager
82
Silent Lion
user23@example.com
Admin
16
Bold Eagle
user24@example.com
Admin
38
1–25 of 240
pnpm dlx shadcn@latest add @gridcn/data-grid-pagination

Page the grid

Pass the whole array as data and set defaultPageSize on the provider. The grid keeps every row and shows one page of the sorted and filtered view. DataGridPaginationBar with no props reads the pager from the provider:

"use client";

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

type Order = { id: string; customer: string };

const columns = defineColumns<Order>()([
  { id: "customer", header: "Customer", accessorKey: "customer" },
]);

function OrdersGrid({ rows }: { rows: Order[] }) {
  return (
    <DataGridProvider defaultData={rows} columns={columns} defaultPageSize={25}>
      <DataGridRoot>
        <DataGridHeader />
        <DataGridBody />
      </DataGridRoot>
      <DataGridPaginationBar />
    </DataGridProvider>
  );
}

The provider keeps the page and the page size in its own state:

  • defaultPage and defaultPageSize seed them once.
  • To control a value, pass page with onPageChange, or pageSize with onPageSizeChange.
  • actions.setPage(page) and actions.setPageSize(size) change them from code. actions.setPageSize(null) turns paging off and calls onPageChange(1) when the page was not 1.
  • A controlled pageSize of null shows every row, and onPageSizeChange receives null when paging turns off.

If the data shrinks, the grid shows the last page. A page-size change keeps the first visible row on screen. A filter change goes back to page 1 and calls onPageChange(1), also when the filter comes from props.

onPageChange and onPageSizeChange run after the grid writes the page or the size. If one throws, the change stays, and a size change still fires onPageChange. Then the grid rethrows the error. See Callback timing and errors.

PropTypeDefault
pageSizenumber | nullnone (every row shows)
defaultPageSizenumber | nullnone
onPageSizeChange(pageSize: number | null) => voidnone
pagenumber1
defaultPagenumber1
onPageChange(page: number) => voidnone

The whole array stays in the grid

The grid holds every row. Only the rows on screen are one page. The footer shows the count of the rows that the sort and filter leave.

  • Sort and filter cover every row, not the page. A header click sorts the whole array.
  • Quick search counts the matches on every page, marks the ones on the shown page, and never filters. Next and previous match jump to the page of the match.
  • Find and replace searches every page. "Replace all" covers every page.
  • Row order. reorderRows and moveRowsBy take page rows, and a move stays inside the shown page. The checked rows and the active cell follow their rows. A sort or filter still blocks them.
  • Edits, inserts, and deletes reach onDataChange with the whole array. Store it as it is.
  • Selection follows row ids. A page change clears the active cell. It also drops the checks and the cell range of rows that left the page. Search and find and replace still select the match they jump to. To keep the checks, pass checkedRowsLifetime="across-filters": the grid remembers each check by row id and restores it on a return to the page. The header checkbox, Mod+Shift+Enter (toggleAllRows), and setAllRowsChecked check the rows of the shown page only. The status bar then offers "Select all 120 matching", and selectAllMatching() checks the rows of every page.
  • Copy, paste, fill, and Delete act on the shown page. A column selection covers the rows of the shown page, and a paste stops at the page's last row.
  • Streaming patches reach every row, also rows on other pages.
  • Totals from pinned rows cover every page. Pass scope: "page" to aggregateRow to total the shown page only.
  • Export and print cover every page. Pass scope: "page" to exportGrid or printGrid to write the shown page only.
  • Announcements from announceResults count the rows of every page.

Read the pager from your own components with const { pager } = useDataGridPager() under the provider. It returns the same controls that the bar uses. useDataGridPager({ pageSizeOptions }) sets the sizes of the select.

Page a list outside the grid

useDataGridPagination slices an array for a list that is not a grid. It returns pageData, the rows of the current page, and pager for the footer:

"use client";

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

type Order = { id: string; customer: string };

function OrderList({ rows }: { rows: Order[] }) {
  const { pageData, pager } = useDataGridPagination({
    data: rows,
    defaultPageSize: 25,
  });
  return (
    <>
      <ul>
        {pageData.map((row) => (
          <li key={row.id}>{row.customer}</li>
        ))}
      </ul>
      <DataGridPaginationBar {...pager} />
    </>
  );
}

The hook takes page, pageSize, defaultPage, defaultPageSize, onPageChange, and onPageSizeChange, named as on the provider. Its page sizes are numbers, so it takes no null. It also takes pageSizeOptions (default [10, 25, 50, 100]). Do not pass pageData to a grid. Page the grid with pageSize on the provider, so sort, filter, and totals cover every row.

DataGridPaginationBar takes the pager object, or none inside a paged provider, plus these props:

PropTypeDefault
pageSizeOptionsreadonly number[][10, 25, 50, 100]
classNamestringnone
labelsPartial<DataGridPaginationLabels>labels.pagination of the grid
windowSizenumber5
childrenReactNodethe default layout

The default layout has a range label, a page-size select, first and previous buttons, a sliding window of page numbers, and next and last buttons. The window stays centered on the current page. Inside DataGridProvider the bar reads the pager of the grid. Outside it, or for a list or a server grid, spread a pager onto it. Its root carries data-grid-pagination.

With children, the bar renders only the parts that you pass. This footer has no page numbers:

import {
  DataGridPaginationBar,
  DataGridPaginationFirst,
  DataGridPaginationLast,
  DataGridPaginationNext,
  DataGridPaginationPrev,
  DataGridPaginationRange,
  type DataGridPaginationControls,
} from "@/components/data-grid-pagination/data-grid-pagination";

function CompactBar({ pager }: { pager: DataGridPaginationControls }) {
  return (
    <DataGridPaginationBar {...pager}>
      <DataGridPaginationRange />
      <div className="flex items-center gap-1">
        <DataGridPaginationFirst />
        <DataGridPaginationPrev />
        <DataGridPaginationNext />
        <DataGridPaginationLast />
      </div>
    </DataGridPaginationBar>
  );
}

The other parts are DataGridPaginationPageSize and DataGridPaginationPages. A part reads its controls and labels from the bar, so it throws outside DataGridPaginationBar. The default strings are the labels.pagination group. Inside a DataGridProvider, the bar reads the labels.pagination of the grid. The labels prop of DataGridPaginationBar overrides both. See Labels.

Pages of groups

While groupBy is set, a page holds pageSize top-level groups with the rows opened under them. pager.unit is "groups", and the footer reads labels.pagination.rangeGroups. A change of groupBy returns to page 1. See Row grouping.

Server mode

For server data, use useDataGridServerRows. It fetches each page and returns the pager. If you fetch with your own code, useDataGridServerPager({ page, pageSize, totalRowCount, hasMore, onPageChange }) builds the pager and returns { pager }. Load rows by page owns the detail. Keep pages in URL covers a page in the address bar.

On this page