Pagination Controls
Explore interactive examples and all component variations in our Storybook.
The PaginationControls component provides a comprehensive pagination interface with page numbers, navigation buttons, and item counters. Built with accessibility and usability in mind, it handles large datasets efficiently with smart page number truncation. Perfect for data tables, search results, and any interface displaying paginated content.
Basic Usage
Data Table Integration
Custom Counter Text
Default Counter
Custom Counter Text
No Counter
Large Dataset Example
Large Dataset Pagination
This example shows how the pagination handles large datasets with smart truncation. Notice how it shows ellipsis (...) to indicate hidden pages.
Current page: 1
Total pages: 250
Items per page: 50
Search Results Integration
Search Results
Found 73 resultsProperties
PaginationControls
| Property | Type | Default | Description |
|---|---|---|---|
currentPage | number | - | The current active page number. |
totalPages | number | - | Total number of pages available. |
totalItems | number | - | Total number of items across all pages. |
startIndex | number | - | Zero-based start index of current page items. |
endIndex | number | - | Zero-based end index of current page items. |
onPageChange | (page: number) => void | - | Callback fired when a specific page is selected. |
onPreviousPage | () => void | - | Callback fired when previous button is clicked. |
onNextPage | () => void | - | Callback fired when next button is clicked. |
showItemsCounter | boolean | true | Whether to display the items counter text. |
counterText | string | 'Showing {{startIndex}} to {{endIndex}} of {{totalItems}} results' | Template string for the counter text. |
className | string | - | Additional CSS classes for the container. |
Counter Text Variables
The counterText prop supports template variables that are automatically replaced:
| Variable | Description | Example Value |
|---|---|---|
{{startIndex}} | First item number on current page (1-based) | 21 |
{{endIndex}} | Last item number on current page | 30 |
{{totalItems}} | Total number of items | 156 |
Page Number Algorithm
The component uses smart truncation for large datasets:
- Small datasets (≤7 pages): Shows all page numbers
- Large datasets (>7 pages): Shows first page, ellipsis, current page ±1, ellipsis, last page
- Current page context: Always shows 1-2 pages around the current page
- Ellipsis indicators: Shows "..." when pages are hidden
Accessibility
The PaginationControls component includes comprehensive accessibility features:
- Keyboard Navigation - Tab navigation through all interactive elements
- Screen Reader Support - Proper ARIA labels and page announcements
- Focus Management - Clear focus indicators on buttons
- Disabled States - Previous/next buttons disabled at boundaries
- Semantic HTML - Uses proper button elements with descriptive labels
- Page Context - Current page clearly indicated visually and programmatically
Common Use Cases
The PaginationControls component is perfect for:
- Data Tables - Navigate through large datasets efficiently
- Search Results - Browse through search result pages
- Product Catalogs - Navigate product listings in e-commerce
- User Lists - Manage large user directories
- Content Archives - Browse blog posts, articles, or documents
- Admin Dashboards - Navigate through administrative data
- API Results - Handle paginated API responses
- File Browsers - Navigate through file listings
Best Practices
- Consistent Page Sizes - Use consistent items per page across your application
- Loading States - Show loading indicators during page transitions
- URL Synchronization - Sync current page with URL parameters when possible
- Mobile Optimization - Ensure pagination works well on small screens
- Performance - Implement virtual scrolling for very large datasets
- Error Handling - Handle edge cases like empty results gracefully
- Analytics - Track pagination usage to optimize page sizes
- Accessibility Testing - Test with screen readers and keyboard navigation