Pagination

Navigation component for splitting content across multiple pages, with support for page size selection and keyboard navigation.

Basic Usage

Current page: 1 of 10

Variants

Default

Outlined

Sizes

Small

Medium (Default)

Large

Without First/Last Buttons

Current page: 5 of 20

With Page Size Selector

Showing page 1 of 15 with 20 items per page

Page Range Examples

Few pages (5 total)

Shows all page numbers when total is 7 or less

Many pages (50 total, page 1)

Shows ellipsis when needed

Many pages (50 total, page 25)

Shows current page in middle with ellipsis on both sides

Many pages (50 total, page 48)

Shows last pages when near the end

Props

Name	Type	Default	Description
`currentPage*`	`number`	-	Current active page (min: 1)
`totalPages*`	`number`	-	Total number of pages (min: 1)
`onPageChange*`	`(page: number) => void`	-	Callback when page changes
`showFirstLast`	`boolean`	`true`	Whether to show first/last page buttons
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Size of pagination controls
`variant`	`'default' \| 'outlined'`	`'default'`	Visual style of pagination
`pageSize`	`number`	-	Current page size (enables page size selector)
`pageSizeOptions`	`number[]`	`[10, 20, 50, 100]`	Available page size options
`onPageSizeChange`	`(size: number) => void`	-	Callback when page size changes
`className`	`string`	-	Additional CSS classes

Usage Guidelines

When to use

•For large datasets that need to be split across multiple pages
•For tables with many rows that would be overwhelming on one page
•When users need to navigate between pages of content systematically
•For search results or list views with many items

Best practices

•Show total page count to help users understand the data size
•Reset to page 1 when page size changes to avoid empty pages
•Display item range (e.g., "Showing 21-40 of 100") for context
•Use appropriate page size defaults (10-50 items) based on content type
•Consider infinite scroll for mobile or casual browsing experiences
•Disable navigation buttons when on first/last page to prevent confusion

Accessibility

•Navigation role with aria-label="pagination" for screen readers
•Current page marked with aria-current="page"
•Keyboard accessible with Tab navigation and Enter/Space activation
•Clear aria-labels on all navigation buttons (First, Previous, Next, Last)
•Visible focus indicators on all interactive elements
•Page size selector properly labeled with associated label element

Do's and Don'ts

✓ Do

•Show item range and total count for context
•Reset to page 1 when changing page size
•Use ellipsis (...) for large page ranges
•Provide reasonable page size options (10, 20, 50, 100)
•Disable navigation when on first/last page

Showing 21-40 of 100 items

✗ Don't

•Don't show pagination without context (no item counts)
•Don't use pagination for small datasets (less than 20 items)
•Don't show all page numbers when there are 50+ pages
•Don't forget to recalculate total pages when page size changes
•Don't enable navigation buttons when they have no action