Pagination

Introduction

The Pagination component provides a navigation system for multi-page content with first, previous, next, and last page controls. It’s built with accessibility in mind, featuring proper ARIA labels, keyboard navigation, and clear visual states.

When to use

Use the Pagination component when you need to split content across multiple pages:

• Blog post listings
• Search results
• Product catalogs
• Image galleries
• Data tables
• Long form content

Progressive enhancement

The component automatically disables navigation controls when no valid URL is provided, ensuring a good user experience even at page boundaries.

Usage

Learn how to implement the Pagination component in your project, from basic usage to advanced configurations.

Basic

---
import { Pagination } from 'accessible-astro-components'
---

<Pagination
  firstPage="/blog/1"
  previousPage="/blog/4"
  nextPage="/blog/6"
  lastPage="/blog/12"
  currentPage="5"
  totalPages="12"
  ariaLabel="Blog navigation"
/>

Custom progress text

---
import { Pagination } from 'accessible-astro-components'
---

<Pagination
  currentPage="5"
  totalPages="12"
  renderProgress={({ currentPage, totalPages }) =>
    `${currentPage} of ${totalPages} pages`
  }
/>

Custom progress text

You can customize the progress text using the renderProgress prop. It’s a function that receives the current page and total pages as arguments and returns a string.

Custom labels

---
import { Pagination } from 'accessible-astro-components'
---

<Pagination
  currentPage="5"
  totalPages="12"
  renderPageLabel={({ type, page }) => {
    switch (type) {
      case 'first':
        return `Navigate to first page (page 1)`
      case 'previous':
        return `Navigate to previous page (page ${page})`
      case 'next':
        return `Navigate to next page (page ${page})`
      case 'last':
        return `Navigate to last page (page ${page})`
    }
  }}
/>

Accessible labels

The renderPageLabel prop allows you to customize the accessible labels for each navigation control while maintaining both context (“next”, “previous”) and specific page numbers for optimal screen reader experience.

Props

Configure the Pagination component using these available props to customize its behavior and appearance.

Prop	Type	Default	Description
firstPage	string | null | undefined	'#'	URL for the first page, falsy value disables the control
previousPage	string | null | undefined	'#'	URL for the previous page, falsy value disables the control
nextPage	string | null | undefined	'#'	URL for the next page, falsy value disables the control
lastPage	string | null | undefined	'#'	URL for the last page, falsy value disables the control
currentPage	string | number	'1'	Current page number
totalPages	string | number	'12'	Total number of pages
renderProgress	Function	See example	Custom function to render the progress text
renderPageLabel	Function	See example	Custom function to generate accessible labels for navigation controls
ariaLabel	string	'Pagination'	Accessible label for the navigation
class	string	''	Additional CSS classes to apply

Accessibility

Accessibility isn’t an afterthought - it’s built into the core of this component through semantic HTML elements and proper ARIA attributes. The Pagination component is built with accessibility in mind:

• Semantic <nav> element with descriptive aria-label
• Clear visual indication of disabled controls
• Descriptive ARIA labels combining both context and page numbers (e.g., “Go to next page (page 6)”)
• Keyboard navigation support
• High contrast icons and text
• Clear focus indicators
• Proper disabled states

Screen readers

The component uses descriptive ARIA labels like “Go to first page” to ensure clear navigation for screen reader users.

Styling

Maintain accessibility

When customizing styles, ensure you maintain sufficient color contrast ratios and don’t remove focus indicators or other accessibility features.

The component includes built-in styling with light and dark mode support. You can customize its appearance while maintaining accessibility:

Custom CSS

/* Option 1: Using :global() in your style block */
<style>
  :global(.pagination .list) {
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  :global(.pagination a),
  :global(.pagination .disabled) {
    display: flex;
    place-items: center;
    inline-size: 2rem;
    block-size: 2rem;
    border: 2px solid;
    border-radius: 0.25rem;
  }

  :global(.pagination a) {
    border-color: light-dark(hsl(204 8% 40%), hsl(215 25% 65%));
  }
</style>

/* Option 2: Using is:global on the style tag */
<style is:global>
  .pagination .list {
    display: flex;
    align-items: center;
    gap: 1rem;
  }

  .pagination a,
  .pagination .disabled {
    display: flex;
    place-items: center;
    inline-size: 2rem;
    block-size: 2rem;
    border: 2px solid;
    border-radius: 0.25rem;
  }

  .pagination a {
    border-color: light-dark(hsl(204 8% 40%), hsl(215 25% 65%));
  }
</style>

Tailwind Classes

<Pagination
  class="rounded-lg shadow-md"
/>

Style scoping

Astro components use scoped styles by default. To override component styles, you’ll need to use either :global() selectors or the is:global directive on your style tag.

Interactive example

See the Pagination component in action with this practical example:

• Page 5 of 12