Skip to main content

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's offset and pageSize, and the filtered list's length as total.
  • Beside a DataTable, pass pageIndex * pageSize and getRowCount().

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:

CursorPagination.Root├── CursorPagination.PageSizeSelect├── CursorPagination.PageSizeValue└── CursorPagination.Buttons

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:

PropTypeDefaultDescription
defaultPageSize?numberThe initial number of items per page. The root owns the value after mount.
pageSize?numberThe controlled number of items per page. Pair it with onChangePageSize; the select shows this value.
onChangePageSize?(pageSize: number) => voidCalled with the next number of items per page when PageSizeSelect changes it.

CursorPagination.Buttons

A pair of previous/next buttons for navigating between pages.

PropTypeDefaultDescription
hasNextPagebooleanWhether there is a next page of data to load.
hasPreviousPagebooleanWhether there is a previous page of data to load.
onNextPage?() => voidCallback called when the next page button is clicked.
onPreviousPage?() => voidCallback called when the previous page button is clicked.

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:

PropTypeDefaultDescription
pageSizes?readonly number[][5, 10, 20, 50, 100]The page sizes to choose from. The current page size must be in this list.
onChangePageSize?(pageSize: number) => voidCalled with the next number of items per page when the user picks one, after Root's callback.
aria-label?string"Items per page"The accessible name of the combobox. Override it for localization.

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:

PropTypeDefaultDescription
offsetnumberThe index of the first row on the page, from 0. A non-negative integer.
pageSizenumberThe most rows a page holds. A positive integer.
totalnumberHow many rows the list holds after its filter. A non-negative integer.
noun?{ singular: string; plural: string }{ singular: "result", plural: "results" }The noun to count, in both forms, because an English plural is irregular.
asChild?booleanfalseRenders the text in your own element. The child must have no children of its own.
Data AttributeValueDescription
data-slot"pagination-range"On the root.

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

ParameterTypeDefaultDescription
listSizenumberThe total number of items in the list. A change resets the page to 1 unless resetPageOnListSizeChange is false.
pageSizenumberThe number of items per page. A change resets the page to 1.
defaultPage?number1The 1-indexed page to start on when uncontrolled.
page?numberThe controlled 1-indexed page. Pair it with onPageChange. currentPage normalizes it: a page past the end clamps, a fraction rounds down, and NaN reads as 1.
onPageChange?(page: number) => voidCalled with the next page when the hook changes it. Not called when the next page equals the stored page. A move onto a normalized currentPage still calls it, so a stale page catches up.
resetPageOnListSizeChange?booleantrueWhether a listSize change resets the page to 1. Set false to keep the page, clamped to the new totalPages.

Return value

The hook returns an object with the current pagination state and navigation helpers:

PropertyTypeDescription
currentPagenumberThe current page number, 1-indexed (starting at 1).
totalPagesnumberThe total number of pages.
hasPreviousPagebooleanWhether there is a previous page.
hasNextPagebooleanWhether there is a next page.
offsetnumberThe offset of the current page within the list.
pageSizenumberThe current number of items per page.
nextPage() => voidGo to the next page.
previousPage() => voidGo to the previous page.
goToPage(page: number) => voidGo to a specific page (clamped to the valid range).
goToFirstPage() => voidGo to the first page.
goToLastPage() => voidGo to the last page.
setPageSize(size: number) => voidSet the number of items per page; resets to the first page.

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.