Pagination

Navigate through pages of content with customizable pagination controls.

Basic Usage

Current page: 1

import { Pagination } from '@akitectio/aki-ui';

function MyComponent() {
  const [currentPage, setCurrentPage] = useState(1);

  return (
    <Pagination
      totalPages={10}
      currentPage={currentPage}
      onPageChange={setCurrentPage}
    />
  );
}

Sizes

Small

Medium (Default)

Large

<Pagination size="sm" totalPages={5} currentPage={1} onPageChange={handlePageChange} />
<Pagination size="md" totalPages={5} currentPage={1} onPageChange={handlePageChange} />
<Pagination size="lg" totalPages={5} currentPage={1} onPageChange={handlePageChange} />

Advanced Configuration

<Pagination
  totalPages={20}
  currentPage={currentPage}
  onPageChange={setCurrentPage}
  maxVisiblePages={7}
  showFirstLast={true}
  showPrevNext={true}
  rounded={true}
  labels={{
    first: 'First',
    last: 'Last',
    previous: 'Prev',
    next: 'Next',
  }}
/>

Interactive Example

Data Table with Pagination

ID	Name	Email	Status
1	User 1	user1@example.com	Active
2	User 2	user2@example.com	Active
3	User 3	user3@example.com	Active
4	User 4	user4@example.com	Active
5	User 5	user5@example.com	Active

Showing 1 to 5 of 50 results

API Reference

Prop	Type	Default	Description
totalPages	number	-	The total number of pages
currentPage	number	-	The current active page (1-indexed)
onPageChange	(page: number) => void	-	Callback function called when a page is clicked
className	string	''	Additional CSS classes to apply
maxVisiblePages	number	5	The maximum number of page buttons to show
showFirstLast	boolean	true	Whether to show the first and last page buttons
showPrevNext	boolean	true	Whether to show the previous and next page buttons
size	'sm' \| 'md' \| 'lg'	'md'	The size of the pagination buttons
rounded	boolean	false	Whether the pagination should have rounded appearance
labels	object	See below	Labels for the navigation buttons

Labels Object

Property	Type	Default	Description
first	string	'«'	Label for the first page button
last	string	'»'	Label for the last page button
previous	string	'‹'	Label for the previous page button
next	string	'›'	Label for the next page button

Accessibility

✅ Full keyboard navigation support
✅ Screen reader compatible with proper ARIA attributes
✅ Focus management and visible focus indicators
✅ Semantic HTML structure
✅ High contrast mode support

ARIA Attributes

aria-label - Descriptive labels for navigation buttons
aria-current="page" - Indicates the current page
role="navigation" - Identifies the pagination as navigation
aria-label - Overall pagination description

Best Practices

✅ Do

Show pagination when there are more than 10-20 items
Display the total number of pages or items when helpful
Use consistent page sizes throughout your application
Consider mobile-friendly compact pagination for small screens
Provide feedback about current position (e.g., "Page 3 of 10")
Maintain pagination state when navigating back

❌ Don't

Use pagination for small datasets (less than 10 items)
Show too many page numbers on mobile devices
Reset to page 1 when applying filters or sorting
Use pagination without showing loading states
Make pagination buttons too small for touch interaction
Hide essential information about total results

Common Use Cases

📊 Data Tables

Navigate through large datasets with pagination controls

User lists, transaction history, product catalogs
Combined with search and filtering
Server-side or client-side pagination

📝 Content Lists

Browse through articles, posts, or media collections

Blog posts, news articles, gallery images
Comments and reviews
Search results and category listings

🛍️ E-commerce

Navigate product listings and order history

Product catalogs with filtering
Order history and tracking
Customer reviews and ratings