Controlled client-side pagination
Keep the current page and page size in component state while controlling a table.
TanStack · Type Alias
PaginationState
PaginationState is TanStack Table’s feature-specific type for pagination state. It contains a zero-based page index and the number of rows per page.
How it works
PaginationState is the feature-specific state shape for TanStack Table pagination. It stores the currently selected zero-based page through pageIndex and the number of rows requested per page through pageSize, and can be used for local state or external atoms.
Syntax
type PaginationState = {
pageIndex: number
pageSize: number
}Parameters
| Name | Type | Description |
|---|---|---|
pageIndex | number | Zero-based index of the active page. |
pageSize | number | Number of rows displayed or requested per page. |
Returns
An object containing pageIndex and pageSize.
Key points
- pageIndex identifies the selected page using zero-based indexing.
- pageSize records how many rows the current pagination configuration requests per page.
- Use PaginationState when defining local state or an external atom for the pagination slice.
- The same state shape applies with either client-side pagination or manually fetched server-side pages.
Common mistakes
- It is an object with exactly the documented pagination properties, pageIndex and pageSize; do not treat it as a numeric page value.
- pageIndex starts at 0 for the first page, so UI page numbers may need a +1 conversion.
- When a query key or other external consumer needs pagination, keep the slice in external state rather than assuming the table instance is the only source.
Example: Define pagination state
type PaginationState = {
pageIndex: number
pageSize: number
}
const pagination: PaginationState = {
pageIndex: 0,
pageSize: 10,
}Creates a valid pagination state with a zero-based page index and a page size of ten.
When to use it
Server-side data queries
Use pageIndex and pageSize to identify and fetch a server-side page.
External state or atoms
Share pagination state with code outside the table instance.
Interview questions
QWhat does PaginationState contain?
PaginationState is the state object used for table pagination. Its pageIndex is zero-based, and pageSize specifies how many rows belong to a page.
Follow-up: How would you use it with server-side fetching? Include the pagination object in the query key and use it to request the corresponding page and size.
QWhen should you use PaginationState instead of a broader table-state type?
Use PaginationState when creating local state or an external atom for only the pagination slice. The documentation recommends feature-specific state types such as PaginationState for that purpose.
Follow-up: Why prefer the feature-specific type? It keeps the state contract narrow and aligned with the table feature being controlled.
QWhy control PaginationState outside the table?
The state can be controlled externally and supplied back to the table, allowing another owner to react to pagination changes. This is useful when pagination must also drive data fetching.
Follow-up: What should a server-side result provide alongside the requested rows? Return the rows for the requested page and the total row count so the table can derive pagination information.
Related
SortingStateRowSelectionStateinitialStatepaginationonPaginationChangerowPaginationFeature