Chakra UI Pagination + React Query: Controlled or Uncontrolled State?

Answer: Keep Pagination controlled

The Chakra UI Pagination component is stateless and requires page (or pageIndex) and onPageChange. To stay in sync with React Query, the single source of truth for the current page should live in your own state (or URL) and be passed into both the query key and the Pagination props.

Why this works (confirmed facts)

• React Query refetches automatically when any item in its queryKey changes.
• Chakra UI’s Pagination never mutates the page internally when page is supplied; it only calls onPageChange with the new value.
• Thus mutating the shared page state triggers a query key change, which causes a refetch, and the updated data flows back to the same state via the handler—no round‑trip effect needed.

Steps to implement

1. Declare page state: const [page, setPage] = useState(1);
2. Build the query key with the page (and pageSize/filters): queryKey: ['items', { page, pageSize, filters }]
3. Render Pagination controlled:

   <Pagination.Root
     count={total}
     pageSize={pageSize}
     page={page}
     onPageChange={(e) => setPage(e.page)}>
     {/* pagination items */}
   </Pagination.Root>

4. Enable placeholder data to avoid UI jumps: keepPreviousData: true (v4) or placeholderData: keepPreviousData (v5).
5. When filters or pageSize change, reset page to 1 (e.g., inside the setter for those values) and optionally key the Pagination by the filter signature to force a remount.
6. Clamp page to the valid range: const maxPage = Math.max(1, Math.ceil(total / pageSize)); const clamped = Math.min(page, maxPage); and use clamped as the value passed to Pagination.

Missing diagnostic detail

To verify that the API matches the example, confirm which version of @chakra-ui/react you have installed. Chakra UI v2 does not export a Pagination component; v3 introduces the controlled/uncontrolled API shown above.