# Pagination **Category**: react **URL**: https://www.heroui.com/docs/react/migration/pagination **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/migration/(components)/pagination.mdx > Migration guide for Pagination from HeroUI v2 to v3 *** Refer to the [v3 Pagination documentation](/docs/react/components/pagination) for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2. ## Structure Changes In v2, `Pagination` was a single component that handled all rendering internally via props: ```tsx import { Pagination } from "@heroui/react"; export default function App() { return ( ); } ``` In v3, Pagination uses a compound component pattern where you compose each part explicitly: ```tsx import { Pagination } from "@heroui/react"; export default function App() { return ( 1 2 3 10 ); } ``` ## Key Changes ### 1. Component Structure **v2:** Single `Pagination` component that auto-generates page items from `total` prop **v3:** Compound components: `Pagination`, `Pagination.Summary`, `Pagination.Content`, `Pagination.Item`, `Pagination.Link`, `Pagination.Previous`, `Pagination.PreviousIcon`, `Pagination.Next`, `Pagination.NextIcon`, `Pagination.Ellipsis` ### 2. Page Generation **v2:** Pages auto-generated from `total`, `siblings`, `boundaries` props **v3:** You compose page items manually, giving full control over layout and behavior. Build your own pagination logic or use a pagination hook. ### 3. Prop Changes | v2 Prop | v3 Equivalent | Notes | |---------|---------------|-------| | `total` | - | Removed (compose items manually) | | `page` | - | Manage active state via `isActive` on `Pagination.Link` | | `initialPage` | - | Manage state externally | | `onChange` | - | Use `onPress` on individual `Pagination.Link` components | | `siblings` | - | Removed (compose items manually) | | `boundaries` | - | Removed (compose items manually) | | `dotsJump` | - | Removed (handle ellipsis click manually) | | `loop` | - | Removed (implement manually) | | `showControls` | - | Compose `Pagination.Previous` and `Pagination.Next` | | `isCompact` | - | Removed (style with Tailwind CSS) | | `showShadow` | - | Removed (use Tailwind `shadow-*` classes) | | `size` | `Pagination` `size` | Same (`sm`, `md`, `lg`) | | `variant` | - | Removed (use Tailwind CSS) | | `color` | - | Removed (use Tailwind CSS) | | `radius` | - | Removed (use Tailwind CSS) | | `isDisabled` | `isDisabled` on `Pagination.Link`, `Pagination.Previous`, `Pagination.Next` | Per-item instead of global | | `disableCursorAnimation` | - | Removed | | `disableAnimation` | - | Removed | | `renderItem` | - | Compose items directly | | `getItemAriaLabel` | - | Set `aria-label` on individual items | | `classNames` | - | Use `className` on individual compound components | ### 4. Hook Changes **v2:** `usePagination` hook available for custom implementations **v3:** No built-in hook — compose pagination items directly or build your own pagination logic ## Migration Examples ### Basic Pagination ```tsx import { Pagination } from "@heroui/react"; ``` ```tsx import { useState } from "react"; import { Pagination } from "@heroui/react"; const [page, setPage] = useState(1); const totalPages = 10; {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => ( setPage(p)}> {p} ))} ``` ### With Previous / Next Controls ```tsx ``` ```tsx const [page, setPage] = useState(1); const totalPages = 10; setPage((p) => Math.max(1, p - 1))} > {Array.from({ length: totalPages }, (_, i) => i + 1).map((p) => ( setPage(p)}> {p} ))} setPage((p) => Math.min(totalPages, p + 1))} > ``` ### With Ellipsis ```tsx ``` ```tsx const [page, setPage] = useState(1); const totalPages = 20; setPage((p) => Math.max(1, p - 1))} > setPage(1)}> 1 {page > 3 && ( )} {[page - 1, page, page + 1] .filter((p) => p > 1 && p < totalPages) .map((p) => ( setPage(p)}> {p} ))} {page < totalPages - 2 && ( )} setPage(totalPages)} > {totalPages} setPage((p) => Math.min(totalPages, p + 1))} > ``` ### Simple Previous / Next Only ```tsx {/* v2 didn't have a built-in simple prev/next pattern */} ``` ```tsx const [page, setPage] = useState(1); const totalPages = 10; setPage((p) => p - 1)} > Previous setPage((p) => p + 1)} > Next ``` ### With Summary ```tsx {/* v2 didn't have a built-in summary slot */} ``` ```tsx const [page, setPage] = useState(1); const perPage = 10; const total = 100; Showing {(page - 1) * perPage + 1}-{Math.min(page * perPage, total)} of {total} {/* Pagination items */} ``` ### Custom Icons ```tsx {/* v2 required renderItem for custom icons */} ``` ```tsx import { Icon } from "@iconify/react"; setPage((p) => p - 1)}> {/* Page links */} setPage((p) => p + 1)}> ``` ## Styling Changes ### v2: `classNames` Prop ```tsx ``` ### v3: Direct `className` Props ```tsx 1 ``` ## Component Anatomy The v3 Pagination follows this structure: ``` Pagination (Root, nav element) ├── Pagination.Summary (optional, info text) └── Pagination.Content (ul container) └── Pagination.Item (li wrapper, repeated) ├── Pagination.Previous (with Pagination.PreviousIcon) ├── Pagination.Link (page number, isActive for current) ├── Pagination.Ellipsis └── Pagination.Next (with Pagination.NextIcon) ``` ## Summary 1. **Component Structure**: Single auto-generating component → compound components with manual composition 2. **Page Generation**: `total`/`siblings`/`boundaries` props → compose page items manually with your own pagination logic 3. **Active Page**: `page`/`initialPage` props → `isActive` prop on individual `Pagination.Link` 4. **Navigation Controls**: `showControls` prop → compose `Pagination.Previous` and `Pagination.Next` directly 5. **Ellipsis**: Auto-generated → compose `Pagination.Ellipsis` manually where needed 6. **Events**: Single `onChange` → individual `onPress` handlers on each `Pagination.Link` 7. **New Features**: `Pagination.Summary` for showing result counts, custom icons via `PreviousIcon`/`NextIcon` children 8. **Hook Removed**: `usePagination` → build your own pagination logic 9. **Styling Props Removed**: `variant`, `color`, `radius`, `isCompact`, `showShadow` → use Tailwind CSS 10. **ClassNames Removed**: Use `className` on individual compound components