Navigation

Pagination

<forma-pagination>

Page navigation with explicit current-page semantics and compact mobile presentation.

Authoring tag
<forma-pagination>
Category
Navigation
Behavior owner
Application / Limen
Canonical source
patterns/pagination.html

Purpose

Pagination moves through a long result set one page at a time. It is a labelled nav of ordinary links: Previous and Next with rel, an ordered list of page links with aria-current="page" on the current one, and a text summary such as "Page 3 of 12". Because every page is a real URL, pages can be bookmarked, opened in new tabs and navigated without script. The application decides page size, which page numbers to show, and how to handle unknown totals or cursor-based APIs.

Use when

  • A list or table has more results than fit comfortably and users benefit from stable, addressable pages.
  • Users need to jump to a specific page or know how far through the results they are.
  • The data source supports page numbers, or at least previous/next cursors.

Avoid when

  • Moving through steps of a task: use Wizard.
  • Switching views of one object: use Tabs.
  • Showing where the user is in a hierarchy: use Scope trail.

Behavior to know

  • Every control is an anchor with a real href; the current page is marked with aria-current="page" and an inverse surface.
  • Each link is at least 44 by 44px.
  • Below 40rem only the current page number stays visible, Previous and Next move to the edges and the summary takes its own line.
  • The summary text states position explicitly, so the current page does not depend on the highlighted box.

Basic example

The smallest correct markup: the canonical pattern from patterns/pagination.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal pagination

Rendered from the canonical pattern file.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Minimal pagination Raw HTML for HTML · Minimal pagination
<forma-pagination class="forma-component-tag">
<nav class="forma-pagination" aria-label="Pagination">
  <a class="forma-pagination__control" href="?page=2" rel="prev">Previous</a>
  <ol class="forma-pagination__pages">
    <li><a href="?page=1">1</a></li>
    <li><a href="?page=2">2</a></li>
    <li><a href="?page=3" aria-current="page">3</a></li>
    <li><a href="?page=4">4</a></li>
    <li><a href="?page=5">5</a></li>
  </ol>
  <a class="forma-pagination__control" href="?page=4" rel="next">Next</a>
  <span class="forma-pagination__summary">Page 3 of 12</span>
</nav>
</forma-pagination>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

First page of results

On page 1 there is nowhere to go back to, so the application omits Previous rather than rendering a dead control.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · First page of results Raw HTML for HTML · First page of results
<forma-pagination class="forma-component-tag">
  <nav class="forma-pagination" aria-label="Audit log pages">
    <ol class="forma-pagination__pages">
      <li><a href="?page=1" aria-current="page">1</a></li>
      <li><a href="?page=2">2</a></li>
      <li><a href="?page=3">3</a></li>
    </ol>
    <a href="?page=2" rel="next">Next</a>
    <span class="forma-pagination__summary">Page 1 of 3</span>
  </nav>
</forma-pagination>

Click or tap the code once to select all of it, then copy.

Scenario

Long result set with gaps

Forty pages with the current page in the middle. The application shows the first and last pages and a window around the current one; the gaps are plain list items with an ellipsis.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Long result set with gaps Raw HTML for HTML · Long result set with gaps
<forma-pagination class="forma-component-tag">
  <nav class="forma-pagination" aria-label="Search result pages">
    <a href="?page=17" rel="prev">Previous</a>
    <ol class="forma-pagination__pages">
      <li><a href="?page=1">1</a></li>
      <li aria-hidden="true">…</li>
      <li><a href="?page=17">17</a></li>
      <li><a href="?page=18" aria-current="page">18</a></li>
      <li><a href="?page=19">19</a></li>
      <li aria-hidden="true">…</li>
      <li><a href="?page=40">40</a></li>
    </ol>
    <a href="?page=19" rel="next">Next</a>
    <span class="forma-pagination__summary">Page 18 of 40 · 1,984 results</span>
  </nav>
</forma-pagination>

Click or tap the code once to select all of it, then copy.

Scenario

Cursor-based paging with an unknown total

The API returns cursors, not page numbers, and does not know the total. Only Previous and Next are rendered and the summary describes the visible range.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

HTML · Cursor-based paging with an unknown total Raw HTML for HTML · Cursor-based paging with an unknown total
<forma-pagination class="forma-component-tag">
  <nav class="forma-pagination" aria-label="Event pages">
    <a href="?before=evt_5120" rel="prev">Newer events</a>
    <a href="?after=evt_5071" rel="next">Older events</a>
    <span class="forma-pagination__summary">Showing 50 events</span>
  </nav>
</forma-pagination>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Compact pagination on a phone

Below 40rem the page list collapses to the current page, Previous and Next sit at the edges and the summary moves to its own centred line.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • Page links other than the current one are hidden below 40rem; the current page stays as the anchor between Previous and Next.
  • The row uses space-between, so Previous and Next land at opposite edges with large 44px targets.
  • The summary is reordered to the end, takes the full width and is centred, so position is still stated in text.
  • Hidden page numbers are removed from the accessibility tree too; the summary and Previous/Next remain the navigation path.
HTML · Compact pagination on a phone Raw HTML for HTML · Compact pagination on a phone
<forma-pagination class="forma-component-tag">
  <nav class="forma-pagination" aria-label="Invoice pages">
    <a href="?page=4" rel="prev">Previous</a>
    <ol class="forma-pagination__pages">
      <li><a href="?page=3">3</a></li>
      <li><a href="?page=4">4</a></li>
      <li><a href="?page=5" aria-current="page">5</a></li>
      <li><a href="?page=6">6</a></li>
      <li><a href="?page=7">7</a></li>
    </ol>
    <a href="?page=6" rel="next">Next</a>
    <span class="forma-pagination__summary">Page 5 of 9</span>
  </nav>
</forma-pagination>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-labelnavstring—Names the landmark. Make it specific when a page has more than one pagination nav.
aria-currentcurrent page linkpageabsentMarks the current page. Forma draws the inverse surface from it and keeps it visible in compact mode.
relPrevious / Next linksprev | next—Declares the relationship between pages for user agents and crawlers.
hreflinksURL—Every page is a real, addressable URL supplied by the application.
aria-hiddenellipsis list itemtrue—Hides decorative gap markers from assistive technology.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-paginationBlock class—Root nav: a wrapping flex row of controls and summary.
.forma-pagination__pagesElement class—Unstyled ordered list of page links in a row.
.forma-pagination__summaryElement class—Small secondary text stating the position, such as Page 3 of 12. Full-width and centred below 40rem.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through Previous, the page links and Next in source order.
EnterFollows the focused link (native).

Form behavior

Does not participate in forms. The application may intercept link clicks for client-side loading but must keep the hrefs valid.

States

Pagination states
StateHow it is expressedPresentation
Current pagearia-current="page"Inverse surface and text color.
Focus:focus-visible on a linkFoundation two-tone focus ring.
At first or last pageapplication omits Previous or NextNo disabled styling exists; do not render a control that goes nowhere.
Compactviewport below 40remOnly the current page number remains between Previous and Next; summary on its own line.

Accessibility

Forma provides

  • Uses a navigation landmark with ordinary links, so pages are reachable without script.
  • Distinguishes the current page by surface inversion and relies on aria-current for the programmatic state.
  • Keeps every link at a 44px minimum target.

Your application supplies

  • Label each pagination nav uniquely.
  • Write a summary that states the page and, when known, the total.
  • Move focus to the top of the updated results (or announce them) when loading a page without a full navigation.

Responsive behavior

  • Wide: a wrapping flex row; page links sit in their own list.
  • Below 40rem: non-current page numbers are hidden, controls spread to the edges and the summary moves to a centred line at the end.
  • Long link text such as Older events wraps with the row rather than overflowing.

Motion

  • No animation: page changes are navigations and the current-page styling is static.

Usage guidance

Do

  • Keep page URLs stable and shareable.
  • Use words like Newer and Older when pages are time-ordered.

Avoid

  • Rendering disabled Previous or Next links; omit them instead.
  • Showing every page number for large result sets.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.