Pagination
Components and hooks for navigating through paged data with cursor-based and offset-based pagination strategies. Use CursorPagination when the data loads by cursor, and the useOffsetPagination hook when it loads by offset.
When to use
- Move through paged data one page at a time, with a cursor or an offset.
- Use cursor pagination for large or real-time data sets, where you cannot jump to a page or know the total.
- Use offset pagination to jump to a specific page and know the total number of pages.
- Put the controls under a
DataTable, as in Within a data table.
Cursor pagination
A pagination component for use with cursor-based pagination. Cursor-based pagination loads data in chunks by using a cursor from the last item on the current page to know where to start the next set. It doesn't let you jump to a specific page or know how many total pages there are, but it's more efficient for large or real-time data sets.
Read-only page size
When the server fixes the page size, show it with CursorPagination.PageSizeValue in place of PageSizeSelect.
Buttons only
Leave out the page size part to show only the buttons. On the first page, pass hasPreviousPage={false} to disable the previous button.
Controlled page size
Root owns the page size when you pass defaultPageSize. When the page size must survive navigation, browser history moves, or a refetch, own it yourself: pass pageSize with onChangePageSize. PageSizeSelect shows the value you pass, so a change from outside the component reaches the select. The demo holds the page size in React state and changes it from a button; a URL search param that a back button rewrites works the same way.
Within a data table
CursorPagination pairs with a DataTable: drive its Buttons and PageSizeSelect from a TanStack Table instance.
Client-paginated
The table holds every row, and the paginatedRowModel slices them. Register rowPaginationFeature and createPaginatedRowModel() with tableFeatures. The table owns the page size, so pass table.state.pagination.pageSize as pageSize and the select follows a setPageSize() call from anywhere. Read getCanPreviousPage() / getCanNextPage() for the buttons and call setPageSize() / setPageIndex(0) when the size changes:
Server cursor data
The server returns one page at a time, so there is no paginatedRowModel and no total count. Wire Buttons to your fetch's has-next / has-prev and load callbacks, and show the fixed, server-controlled page size with the read-only PageSizeValue instead of PageSizeSelect. The example simulates the server's cursor state with a page index:
See the DataTable pagination recipe for the full table markup.
Count line
PaginationRange renders the count line beside the controls, such as "1–10 of 23 payments". The client-paginated example above shows it. It takes the page's offset, the pageSize, and the list's total, so it fits both offset state from useOffsetPagination and a TanStack table instance:
- Beside a
Table, pass the hook'soffsetandpageSize, and the filtered list's length astotal. - Beside a
DataTable, passpageIndex * pageSizeandgetRowCount().
The line is a live region (role="status"), so a screen reader announces the new range when the page changes. It stays in the DOM while the list is empty, because a live region added together with its text isn't announced. It shows the total alone when one page holds every row, and no text for an empty list, which shows its own empty state. Cursor data has no total, so it has no count line.
Composition
Compose the parts of a CursorPagination together to build your own:
API Reference
CursorPagination.Root
The root container for cursor-based pagination. It owns the page size that PageSizeSelect and PageSizeValue read. Pass exactly one of defaultPageSize and pageSize.
All props from the HTML div element, plus:
CursorPagination.Buttons
A pair of previous/next buttons for navigating between pages.
CursorPagination.PageSizeSelect
A select input for changing the number of items per page. Its combobox is named "Items per page" by default, because its visible text is only the current value. Accepts all Select.Trigger props, plus:
CursorPagination.PageSizeValue
Displays the current page size as a read-only value (e.g. "100 per page"). Accepts standard span attributes.
PaginationRange
The count line for one page of a list. It renders a span with role="status". Accepts standard span attributes except children, plus:
Offset pagination
useOffsetPagination
A headless hook for managing offset-based pagination state. Offset-based pagination lets you jump to a specific page and know the total number of pages.
Own the page
The hook owns the page by default. When the page must survive navigation, browser history moves, or a refetch, own it yourself: pass page with onPageChange. Keep the value where you need it, such as a URL search param. Set resetPageOnListSizeChange to false when a refetch can change the list length. The hook then stays on the current page and clamps it to the new page count instead of returning to page 1. The demo holds the page in React state and starts on page 5; the refetch button shrinks the list to 25 items, and the page clamps to 3.
Parameters
Return value
The hook returns an object with the current pagination state and navigation helpers:
getOffsetPaginatedSlice
A utility function to get a paginated slice of a list based on the current offset pagination state. Pair it with useOffsetPagination to render only the current page of items.