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.
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:
defaultPageanddefaultPageSizeseed them once.- To control a value, pass
pagewithonPageChange, orpageSizewithonPageSizeChange. actions.setPage(page)andactions.setPageSize(size)change them from code.actions.setPageSize(null)turns paging off and callsonPageChange(1)when the page was not 1.- A controlled
pageSizeofnullshows every row, andonPageSizeChangereceivesnullwhen 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.
| Prop | Type | Default |
|---|---|---|
pageSize | number | null | none (every row shows) |
defaultPageSize | number | null | none |
onPageSizeChange | (pageSize: number | null) => void | none |
page | number | 1 |
defaultPage | number | 1 |
onPageChange | (page: number) => void | none |
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.
reorderRowsandmoveRowsBytake 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
onDataChangewith 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), andsetAllRowsCheckedcheck the rows of the shown page only. The status bar then offers "Select all 120 matching", andselectAllMatching()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"toaggregateRowto total the shown page only. - Export and print cover every page. Pass
scope: "page"toexportGridorprintGridto write the shown page only. - Announcements from
announceResultscount 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.
The pager footer
DataGridPaginationBar takes the pager object, or none inside a paged provider, plus these props:
| Prop | Type | Default |
|---|---|---|
pageSizeOptions | readonly number[] | [10, 25, 50, 100] |
className | string | none |
labels | Partial<DataGridPaginationLabels> | labels.pagination of the grid |
windowSize | number | 5 |
children | ReactNode | the 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.
Related
- Client pagination options: the full option list
- Load rows by page: server pages with the same footer
- Pinned rows: totals across every page
- Checked rows:
checkedRowsLifetime="across-filters"across pages
Row grouping
Group rows by one or more columns into row groups that open and close, with a count and a reduced value on each group row, on a local array or on your server.
Context menu
Add a header dropdown and right-click menus for sort, pin, hide, clipboard, and row operations, and change the items of each menu.