Atom

Pagination

Navigation component for browsing through pages of data with page size controls.

Overview

The Pagination component provides controls for navigating through paginated data. It displays the current range of items, total count, and navigation buttons. Optionally includes a page size selector.

Rows per page:
1-10 of 100

Props

Prop Type Default Description
totalItems number - Total number of items
currentPage number - Current page (1-indexed)
pageSize number - Number of items per page
pageSizeOptions number[] [10, 25, 50, 100] Available page size options
onPageChange (page: number) => void - Callback when page changes
onPageSizeChange (pageSize: number) => void - Callback when page size changes
rowsPerPageLabel string 'Rows per page:' Label for the page size selector
showRowsPerPage boolean true Whether to show the page size selector
size 'sm' | 'md' 'md' Size variant

Variants

Sizes

Two size options for different contexts.

Small
1-10 of 100
Medium
1-10 of 100
 
<Pagination size="sm" ... />
<Pagination size="md" ... />

Examples

With Page Size Selector

Full pagination with rows per page dropdown.

Rows per page:
1-25 of 500
 
<Pagination
  totalItems={500}
  currentPage={page}
  pageSize={pageSize}
  onPageChange={setPage}
  onPageSizeChange={setPageSize}
  pageSizeOptions={[10, 25, 50, 100]}
  showRowsPerPage
/>

Compact (No Page Size)

Minimal pagination showing only navigation.

1-10 of 50
 
<Pagination
  totalItems={50}
  currentPage={page}
  pageSize={10}
  onPageChange={setPage}
  showRowsPerPage={false}
/>

Custom Label

Customizable label for the page size selector.

Items per page:
1-10 of 100
 
<Pagination
  totalItems={100}
  currentPage={page}
  pageSize={pageSize}
  onPageChange={setPage}
  onPageSizeChange={setPageSize}
  rowsPerPageLabel="Items per page:"
/>

Usage with Tables

Pagination is commonly used with the Table component to navigate through large datasets. Here's a typical pattern: 

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(10);

// Calculate slice indices
const startIndex = (page - 1) * pageSize;
const endIndex = startIndex + pageSize;
const paginatedData = data.slice(startIndex, endIndex);

return (
  <>
    <Table data={paginatedData} columns={columns} />
    <Pagination
      totalItems={data.length}
      currentPage={page}
      pageSize={pageSize}
      onPageChange={setPage}
      onPageSizeChange={(newSize) => {
        setPageSize(newSize);
        setPage(1); // Reset to first page
      }}
    />
  </>
);

Accessibility

  • ARIA Labels: Navigation buttons have descriptive aria-labels.
  • Disabled State: Buttons are properly disabled at boundaries.
  • Keyboard Support: All controls are keyboard accessible.
  • Screen Reader: Page range information is readable by assistive technology.

Best Practices

  • Always show the current range and total items for context
  • Reset to page 1 when changing page size
  • Provide reasonable page size options (not too many, not too few)
  • Consider server-side pagination for large datasets