Pagination

When to use

Add pagination once a list is too long to show all at once and you'd rather split it into discrete pages than load everything, or scroll endlessly, such as search results, a data table, or an admin listing. Prefer infinite list instead when "keep loading more as you scroll" fits the content better than discrete, addressable pages. Reach for pagination when someone benefits from jumping straight to a specific page, sharing a link to it, or seeing roughly how much content there is in total. See Alternatives below for a side by side comparison.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/pagination.js";

<eun-pagination
  page="1"
  total-pages="12"
  aria-label="Pagination"
></eun-pagination>

<script>
  document
    .querySelector("eun-pagination")
    .addEventListener("eunpagechange", (event) => {
      // Apply the change yourself : fetch the new page, update the URL, ...
      event.target.page = event.page;
    });
</script>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/pagination.js";
</script>

<eun-pagination
  page="1"
  total-pages="12"
  aria-label="Pagination"
></eun-pagination>

<script type="module">
  const pagination = document.querySelector("eun-pagination");
  pagination.addEventListener("eunpagechange", (event) => {
    pagination.page = event.page;
    // ... fetch/render the new page's data
  });
</script>

npm install @eunomia/elements

import { useState } from "react";
import "@eunomia/elements/pagination.js";

function ResultsPagination({ totalPages }) {
  const [page, setPage] = useState(1);

  return (
    <eun-pagination
      page={page}
      total-pages={totalPages}
      aria-label="Pagination"
      oneunpagechange={(event) => setPage(event.page)}
    />
  );
}

npm install @eunomia/elements

"use client";
import { useRouter, useSearchParams } from "next/navigation";
import "@eunomia/elements/pagination.js";

export function ResultsPagination({ totalPages }) {
  const router = useRouter();
  const searchParams = useSearchParams();
  const page = Number(searchParams.get("page") ?? 1);

  return (
    <eun-pagination
      page={page}
      total-pages={totalPages}
      aria-label="Pagination"
      oneunpagechange={(event) => {
        const params = new URLSearchParams(searchParams);
        params.set("page", String(event.page));
        router.push(`?${params.toString()}`);
      }}
    />
  );
}

npm install @eunomia/elements

<script setup>
  import { ref } from "vue";
  import "@eunomia/elements/pagination.js";

  const page = ref(1);
</script>

<template>
  <eun-pagination
    :page="page"
    total-pages="12"
    aria-label="Pagination"
    @eunpagechange="page = $event.page"
  />
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/pagination.js";

@Component({
  selector: "app-results-pagination",
  template: `
    <eun-pagination
      [page]="page"
      total-pages="12"
      aria-label="Pagination"
      (eunpagechange)="page = $event.page"
    ></eun-pagination>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ResultsPaginationComponent {
  page = 1;
}

Alternatives

Guidance

Live testing

Properties

page and totalPages are the two you'll always set. Everything else tunes the collapsed-page-range algorithm, hides controls, shows a visible label next to First/Previous/Next/Last (showLabels), relabels controls for another language, or adds a page-size selector (pageSizeOptions, see the Examples tab).

Page range

Basic

Few enough pages that every number fits, so no … gap is needed.

<eun-pagination
  page="2"
  total-pages="5"
  aria-label="Pagination"
></eun-pagination>

Collapsed range

Past a certain page count, the middle collapses into … gaps on one or both sides of the current page, always keeping the first/last boundaryCount pages and the current page's siblingCount neighbors visible.

<eun-pagination
  page="10"
  total-pages="30"
  aria-label="Pagination"
></eun-pagination>

Custom sibling and boundary count

<eun-pagination
  page="10"
  total-pages="30"
  sibling-count="2"
  boundary-count="2"
  aria-label="Pagination"
></eun-pagination>

Controls

Hiding controls

Hide First/Last when jumping straight to either end rarely matters, or Previous/Next when the page numbers alone are enough.

<eun-pagination
  page="10"
  total-pages="30"
  hide-first-last
  aria-label="Pagination"
></eun-pagination>

Labeled controls

showLabels adds a visible text label next to the First/Previous/Next/Last icons, the same strings as their aria-label-*, for a more explicit, less icon-reliant control. The icon always points away from its label (see the Accessibility tab).

<eun-pagination
  page="4"
  total-pages="12"
  show-labels
  aria-label="Pagination"
></eun-pagination>

Disabled while loading

Set disabled while the requested page's data is in flight, so a second click can't race the first. See "SPA and router integration" below for the full pattern.

<eun-pagination
  page="4"
  total-pages="12"
  disabled
  aria-label="Pagination"
></eun-pagination>

Page-size selector

Setting pageSizeOptions renders a eun-select-powered page-size selector alongside the page controls, labeled with pageSizeLabel. Left unset (the default), no selector is rendered at all, since eun-pagination has no page size of its own to offer choices for. Like eunpagechange, eunpagesizechange is a pure request: pageSize is never updated internally, and neither is page/totalPages, since changing how many items fit per page almost always changes the total page count too, which only you know how to recompute.

import "@eunomia/elements/pagination.js";
import "@eunomia/elements/select.js"; // powers the page-size selector

<eun-pagination
  page="1"
  total-pages="10"
  page-size="10"
  page-size-options="[10, 25, 50]"
  aria-label="Pagination"
></eun-pagination>

const pagination = document.querySelector("eun-pagination");

pagination.addEventListener("eunpagesizechange", (event) => {
  const totalItems = 97; // however you know your actual total is
  pagination.pageSize = event.pageSize;
  pagination.totalPages = Math.ceil(totalItems / event.pageSize);
  pagination.page = 1; // the old page position no longer means anything
});

Placement

page-size-placement sets which edge of the row the selector sits against, end by default or start. Its width is 100px by default, and --pagination-page-size-width changes it.

<eun-pagination
  page="4"
  total-pages="12"
  page-size="10"
  page-size-options="[10, 25, 50]"
  page-size-placement="start"
  aria-label="Pagination"
></eun-pagination>

Hiding on narrow widths

page-size-hide-below hides the selector once the pagination is narrower than a breakpoint (mobile, tablet, laptop or desktop) or a number of pixels. The width compared is the pagination's own, not the screen's, so it reacts the same way inside a narrow card or side panel.

<eun-pagination
  page="4"
  total-pages="12"
  page-size="10"
  page-size-options="[10, 25, 50]"
  page-size-hide-below="mobile"
  aria-label="Pagination"
></eun-pagination>

The same threshold can come from CSS with --pagination-page-size-hide-below, to set it once for a whole page or change it from your own media queries. The attribute wins over it when both are set.

eun-pagination {
  --pagination-page-size-hide-below: 520px;
}

@media (width < 1024px) {
  eun-pagination {
    --pagination-page-size-hide-below: tablet;
  }
}

Layout

Alignment

align places the page controls at the start (default), center or end of the row. Centered, they sit in the middle of the whole row, and the page-size selector stays beside them without shifting them off center.

<eun-pagination
  page="4"
  total-pages="12"
  page-size="10"
  page-size-options="[10, 25, 50]"
  align="center"
  aria-label="Pagination"
></eun-pagination>

Narrow spaces

The pagination always stays on a single line. When its row runs out of width, it first drops the visible labels, then the First and Last controls, then the pages around the current one, and finally keeps only the current page between Previous and Next. Everything comes back as soon as there's room again.

<div style="max-width: 280px">
  <eun-pagination
    page="10"
    total-pages="30"
    show-labels
    aria-label="Pagination"
  ></eun-pagination>
</div>

Integration

SPA and router integration

eun-pagination never touches the URL or your router itself. It only tells you which page was requested. The pattern is always the same, regardless of framework: listen for eunpagechange, apply the change however fits your app, then set page back once it's actually done.

const pagination = document.querySelector("eun-pagination");

pagination.addEventListener("eunpagechange", async (event) => {
  pagination.disabled = true; // block a second click while this one's in flight
  await goToPage(event.page); // your own router push / fetch / state update
  pagination.page = event.page;
  pagination.disabled = false;
});

Server-side rendering

The pagination draws its controls from its attributes, so a server-rendered pagination stays empty until the element upgrades, then pushes the content below it down. Link pagination-ssr.css in the page's <head> to reserve the height of its row from the first paint:

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/pagination-ssr.css"
/>

A bundler that resolves package exports can reach it as @eunomia/elements/pagination-ssr.css.

It follows --pagination-item-size. The controls themselves appear with the upgrade, and so does the page-size selector, whose height isn't reserved.

Custom

Override the --pagination-* CSS variables, listed in full in the API tab.

<eun-pagination
  class="custom-pagination"
  page="4"
  total-pages="12"
  aria-label="Pagination"
></eun-pagination>

.custom-pagination {
  --pagination-current-background: #be185d;
  --pagination-item-background-hover: #fce7f3;
  --pagination-border-radius: 999px;
}

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Keyboard interactions

eun-pagination adds no custom keyboard handling of its own, since every control is a native <button> (or, for the current page, plain non-interactive text), so standard button/focus behavior already applies. Unlike a listbox or tablist, there's no dedicated "pagination" pattern in the WAI-ARIA APG requiring roving tabindex or arrow-key navigation between controls, so this deliberately stays a plain sequence of independent buttons rather than a composite widget:

Aria attributes and rules

• Rendered as <nav aria-label="Pagination"> wrapping a <ul role="list">, following the same landmark-plus-list structure as eun-breadcrumb. Its default label follows the active locale, and aria-label overrides it for a specific context.
• role="list" is set explicitly despite <ul> having it implicitly: Safari drops the implicit role once list-style: none is applied (needed here for the visual flex layout), which would otherwise silently skip the list for VoiceOver users.
• The current page renders as a non-interactive <span aria-current="page">, never a button, mirroring eun-breadcrumb's current step, since activating the page someone's already on is a confusing, redundant control.
• First/Previous/Next/Last and every page-number control carry an explicit aria-label (first-label/previous-label/next-label/last-label/page-label), since a lone chevron icon or a bare digit has no accessible name on its own otherwise.
• Unreachable controls (Previous/First on page 1, Next/Last on the last page, or every control while disabled is set) use the native disabled attribute, not aria-disabled, so they're properly excluded from the tab order and announced as unavailable by assistive technology, not just visually dimmed.
• … gaps are rendered as <span aria-hidden="true">…</span>: a purely visual indicator of skipped pages, not a control. There's nothing to activate, so it's excluded from the accessibility tree entirely rather than being a dead, focusable stop.
• While showLabels is set, First/Previous/Next/Last drop their aria-label entirely rather than keeping it alongside the now-visible text, so the button's accessible name comes from its content instead, avoiding two competing sources of truth for the same name, and keeping the visible label and accessible name identical (WCAG 2.5.3, Label in Name). eun-icon stays aria-hidden either way, so it never contributes to that name.
• The page-size selector (pageSizeOptions, see the Examples tab) is a eun-select field, given its own accessible name through pageSizeLabel, so no extra ARIA is needed on top of what it already provides on its own (see the Select component).

No real links, on purpose

Every control is a <button>, never an <a href>. Unlike eun-button/ eun-link, eun-pagination never performs (or lets a router intercept) a native navigation at all. This is deliberate: pages are almost always fetched or rendered client-side rather than served from a distinct URL per page, so there's no href to meaningfully build in the first place. If your pages are individually linkable (e.g. server-rendered ?page=N results), keep the URL in sync yourself from eunpagechange (see "SPA and router integration" in the Examples tab) rather than expecting eun-pagination to manage it.

Reference links

WAI-ARIA Authoring Practices: Patterns
WAI Web Accessibility Tutorials: Labeling Controls