Anatomy
- Previous navigation: Navigation control to move to the previous page, typically featuring a chevron-left icon with "Previous" label
- Page navigation: Sequential page number links that allow direct navigation to specific pages within the current visible range
- Current page: Highlighted page indicator showing the currently active page
- Truncation: Ellipsis (...) indicating that additional pages exist beyond the currently displayed range
- Next navigation: Navigation control to move to the next page, typically featuring a chevron-right icon with "Next" label
Usage Guidelines
When to use this component
- For displaying lists, tables, or content collections with more than 25 items to improve page load performance and user experience
- When loading all content at once would significantly impact page performance or when working with large datasets that benefit from chunked loading
- For content that benefits from sequential browsing, such as search results, product listings, article archives, or data tables
- When screen real estate is limited and showing all content would create overwhelming or unusable interfaces
When not to use this component
- For step-by-step processes, forms, or wizards where users need to complete tasks in sequence. Use Step Indicator instead
- In lists with fewer than 25 items unless there are specific performance or design constraints that justify its use
- When infinite scroll would provide a better user experience, such as continuous browsing scenarios
Best Practices
Use it for lists with more than 25 items.
Do not rely exclusively on Pagination for navigation purposes. Consider providing a search, filters, or any other method to locate the data.
Use truncation to determine the number of pages that will be shown. Be aware of the screen size or space available.
General Component Behaviors
Page selection
Clicking any visible page number immediately navigates to that page and updates the current page indicator. The page becomes selected and highlighted with distinct visual styling.
Sequential navigation
Previous and Next buttons provide one-step navigation in either direction. These buttons automatically disable when users reach the first or last page respectively.
Truncation logic
When the total number of pages exceeds the display limit (typically 5-10 visible pages), truncation ellipsis (...) appear to indicate hidden pages while maintaining access to first, last, and nearby pages.
Placement
The component will always be located below the content being paginated, separated by --w-space-s and right-aligned.
States
There exist four different states for tabs:
- Default: Page number is enabled but is not selected
- Hover: Interactive state when user hovers over an inactive page number
- Active: Currently selected page
- Focused: Keyboard focus state for accessibility compliance
Known Gaps
- Additional accessibility score details and guidelines.