Pagination
A flexible pagination component with animated page transitions, compact mode, configurable sibling counts, and full keyboard accessibility. Supports both controlled and uncontrolled usage patterns.
Live Preview
Interact with the pagination component in real time. Adjust size, mode, and layout options to see changes instantly.
<Pagination
totalPages={10}
size="md"
/>Installation
Install the Aidash Components package using your preferred package manager.
$ pnpm add @aidash/componentsImport
Import the Pagination component into your file.
import { Pagination } from '@/components/aidash/pagination';Basic Usage
The simplest way to use Pagination with default props.
<Pagination totalPages={10} />Sizes
Three sizes to fit different layout contexts and information density.
Small
Medium (default)
Large
1<Pagination totalPages={10} size="sm" />2<Pagination totalPages={10} size="md" />3<Pagination totalPages={10} size="lg" />Compact Mode
A minimal display showing the current page and total in a "3 / 10" format, ideal for tight spaces.
Compact Small
Compact Medium
Compact Large
1{/* Shows "1 / 10" with prev/next arrows */}2<Pagination totalPages={10} compact />3 4{/* Compact with different sizes */}5<Pagination totalPages={10} compact size="sm" />6<Pagination totalPages={10} compact size="lg" />Show First / Last
Toggle the double-chevron buttons that jump to the first and last page.
With First/Last (default)
Without First/Last
1{/* Double-chevron buttons enabled (default) */}2<Pagination totalPages={20} showFirstLast />3 4{/* Double-chevron buttons hidden */}5<Pagination totalPages={20} showFirstLast={false} />Sibling Count
Control how many page numbers are shown on each side of the current page.
siblingCount=1 (default)
siblingCount=2
siblingCount=3
1{/* Shows: 1 ... 9 [10] 11 ... 20 */}2<Pagination totalPages={20} siblingCount={1} defaultPage={10} />3 4{/* Shows: 1 ... 8 9 [10] 11 12 ... 20 */}5<Pagination totalPages={20} siblingCount={2} defaultPage={10} />6 7{/* Shows: 1 ... 7 8 9 [10] 11 12 13 ... 20 */}8<Pagination totalPages={20} siblingCount={3} defaultPage={10} />Controlled Mode
Manage the current page externally with state for full control over pagination behavior.
1const [page, setPage] = useState(1);2 3<Pagination4totalPages={10}5currentPage={page}6onPageChange={setPage}7/>8 9{/* External controls */}10<button onClick={() => setPage(1)}>Reset</button>11<button onClick={() => setPage(5)}>Go to 5</button>Accessibility
Built-in accessibility features for keyboard navigation and screen reader support.
ARIA Labels
The component wraps in a nav element with aria-label="Pagination". Each button has descriptive aria-labels like "Page 3", "Previous page", "First page".
Current Page Indicator
The active page button has aria-current="page" so screen readers announce which page is currently active.
Keyboard Navigation
All buttons are focusable with Tab and activatable with Enter or Space. Disabled buttons at boundaries (first/last page) are properly marked with the disabled attribute.
Disabled State
Navigation buttons are automatically disabled when at the boundary (e.g., "Previous" on page 1) with reduced opacity and cursor-not-allowed.
1{/* The component renders semantic HTML automatically */}2<nav aria-label="Pagination">3<button aria-label="First page" disabled>...</button>4<button aria-label="Previous page" disabled>...</button>5<button aria-label="Page 1" aria-current="page">1</button>6<button aria-label="Page 2">2</button>7<button aria-label="Next page">...</button>8<button aria-label="Last page">...</button>9</nav>API Reference
Complete list of props accepted by Pagination.
| Prop | Type | Default | Description |
|---|---|---|---|
| totalPages | number | — | Total number of pages (required) |
| currentPage | number | — | Controlled current page (makes component controlled) |
| defaultPage | number | 1 | Initial page for uncontrolled mode |
| onPageChange | (page: number) => void | — | Callback fired when page changes |
| size | 'sm' | 'md' | 'lg' | 'md' | Size of the pagination buttons |
| compact | boolean | false | Show compact "3 / 10" style instead of page buttons |
| showFirstLast | boolean | true | Show first/last page navigation buttons |
| siblingCount | number | 1 | Number of sibling pages shown around the current page |
| className | string | '' | Additional CSS classes |
currentPage is provided, the component operates in controlled mode. Without it, the component manages its own state internally using defaultPage as the initial value.Related
Other components that work well alongside Pagination.