Pagination Component — Astro

Pagination Component

An accessible pagination component for navigating between pages. Supports previous/next, first/last, page numbers with ellipsis for long ranges, and a configurable URL pattern.

Add this component

The command below includes <strong>Pagination</strong>—run it in your project directory to install this component (and the CSS if needed). No prompts.

Choose your package manager — click a tab to select, then copy the command.

npm pnpm yarn bun

bash bash Copy code

npx rizzo-css add Pagination

bash bash Copy code

pnpm dlx rizzo-css add Pagination

bash bash Copy code

npx rizzo-css add Pagination

bash bash Copy code

bunx rizzo-css add Pagination

Props

• currentPage (number, required) - The current page number (1-based)
• totalPages (number, required) - Total number of pages
• hrefTemplate (string, optional) - URL pattern with {page} placeholder (default: ?page={page})
• showFirstLast (boolean, optional) - Show First and Last links (default: true)
• maxVisible (number, optional) - Max page numbers to show before using ellipsis (default: 5)
• class (string, optional) - Additional CSS classes

Basic Usage

Click any page to see the current page update. With syncHash, URL hash and current page stay in sync. Pagination script runs after DOM ready when used.

---
import Pagination from '../components/astro/Pagination.astro';
---

<Pagination
  currentPage={3}
  totalPages={10}
  hrefTemplate="?page={page}"
/>

<!-- Rizzo CSS; pagination links. For hash sync include script from package/vanilla docs (runs on DOMContentLoaded). -->
<nav class="pagination" aria-label="Pagination" data-total-pages="10" data-href-template="?page={page}">
  <ul class="pagination__list">
    <li><a href="?page=2" class="pagination__link">Previous</a></li>
    <li><a href="?page=1" class="pagination__link">1</a></li>
    <li><span class="pagination__link pagination__link--current" aria-current="page">2</span></li>
    <li><a href="?page=3" class="pagination__link">3</a></li>
    <li><a href="?page=3" class="pagination__link">Next</a></li>
  </ul>
</nav>

<script>
  import { Pagination } from '$lib/rizzo';
</script>

<Pagination
  currentPage={3}
  totalPages={10}
  hrefTemplate="?page={page}"
/>

<script setup>
import Pagination from '@/components/rizzo/Pagination.vue';
</script>

<template>
  <Pagination
    :current-page="2"
    :total-pages="10"
    href-template="?page={page}"
    show-first-last
    :max-visible="5"
  />
</template>

import { Pagination } from './components/react';

<Pagination
  currentPage={2}
  totalPages={10}
  hrefTemplate="?page={page}"
  showFirstLast
  maxVisible={5}
/>

With Query String

Use hrefTemplate to build URLs. The {page} placeholder is replaced with the page number. For in-page demos we use hash links with syncHash so the current page updates without a full reload:

<Pagination
  currentPage={2}
  totalPages={5}
  hrefTemplate="/blog?page={page}"
/>

Without First/Last

<Pagination
  currentPage={5}
  totalPages={10}
  showFirstLast={false}
  hrefTemplate="?page={page}"
/>

Many Pages (Ellipsis)

When totalPages exceeds maxVisible, ellipsis (…) is shown between the first/last and the range around the current page:

First and Last Page

Previous/Next and First/Last are disabled when on the first or last page:

Verifying the examples

All live examples above use hrefTemplate="#page-{page}" and syncHash. To confirm they work: open this page, click different page numbers (and First/Previous/Next/Last where shown). The URL hash should update (e.g. #page-5) and the current page highlight should move. Changing the hash in the address bar (e.g. to #page-1) should update the highlighted page.

Features

• Semantic markup - <nav aria-label="Pagination"> with list of links
• Previous / Next - Always shown; disabled (non-clickable) on first/last page
• First / Last - Optional; controlled by showFirstLast
• Page numbers - Current page has aria-current="page" and is not a link
• Ellipsis - When many pages, shows 1 … 4 5 6 … 10 style range
• Configurable URLs - hrefTemplate with {page} placeholder
• Theme-aware - Uses design system variables

Other frameworks: Vanilla · Svelte · Vue · React