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.
| Symbol | Purpose | Guide |
|---|---|---|
useDataGridPager | Returns the pager of a grid that pages its view | Client pagination |
DataGridPaginationBar | Renders the footer | Client pagination |
| Footer parts | Compose a custom footer | Client pagination |
useDataGridServerPager | Returns the pager of rows that you fetch yourself | Load rows by page |
useDataGridPagination | Pages a list that is not a grid | Client 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.
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.
| Part | Renders |
|---|---|
DataGridPaginationRange | The range label, the empty label, or "Page 3" when the count is null |
DataGridPaginationPageSize | The rows-per-page select |
DataGridPaginationFirst | A button to page 1, disabled on page 1 |
DataGridPaginationPrev | A button to the previous page, disabled on page 1 |
DataGridPaginationPages | The numbered buttons, windowSize at a time (default 5). The props type is DataGridPaginationPagesProps. |
DataGridPaginationNext | A button to the next page, disabled without a next page |
DataGridPaginationLast | A 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
Related
- Client pagination: how a paged local array behaves.
- Server rows options: the options of
useDataGridServerRows. - Load rows by page: server pages with a pager.
- Labels: the text of the footer.