Pagination

Links to the pages of a long list, each a square target, the current one filled, shrinking to Previous, the current page, and Next when it is narrow.

Example

View Code 
<nav class="pagination" aria-label="Pagination">
    <ol role="list">
        <li><a href="#" rel="prev">Previous</a></li>
        <li><a href="#">1</a></li>
        <li><a href="#" aria-current="page">2</a></li>
        <li><a href="#">3</a></li>
        <li><span>…</span></li>
        <li><a href="#">9</a></li>
        <li><a href="#" rel="next">Next</a></li>
    </ol>
</nav>

When to use it

Under a list that is split into pages: search results, an archive, a table too long for one screen. It is for pages a reader may want to jump between; a feed that only ever goes forward needs one Next link, not this.

How it works

A row of links, each at least a control's width and height so it is easy to hit, the current page filled with the hue. An ellipsis in a span stands for skipped pages. Below data-threshold, the pagination's own width, everything but Previous, the current page, and Next is hidden, so the same markup is a full row in a wide column and three targets in a narrow one, with no breakpoint. data-justify places the row.

<nav class="pagination" aria-label="Pagination" data-justify="center" data-threshold="md">
    <ol role="list">
        <li><a href="#" rel="prev">Previous</a></li>
        <li><a href="#" aria-current="page">1</a></li>
        <li><a href="#">2</a></li>
        <li><a href="#" rel="next">Next</a></li>
    </ol>
</nav>

Accessibility

Label the nav aria-label="Pagination". The current page's link carries aria-current="page", which is also what the fill follows. Previous and Next carry rel="prev" and rel="next" with visible text, or an aria-label if they are icons; they are what remains when the row is narrow, so they must make sense alone. The ellipsis is a span, not a link. role="list" on the ol keeps it a list where the reset removes the markers.

Attributes

Attribute Type Values Default Description
data-threshold enum 2xs, xs, sm, md, lg, xl, 2xl sm The pagination's own width below which only Previous, the current page, and Next remain.
data-variant enum primary, secondary, success, warning, alert, neutral primary The hue of the current page and of the hover tint.
data-justify enum start, center, end, between, around, evenly start Where the links sit in the row.
data-size enum sm, md, lg md The text step.

Children

  • > ol: exactly 1. The links, in page order, with role="list".
  • li: at least 2. A page link, or a span holding an ellipsis for skipped pages.

Tokens

Token Description
--yeti-pagination-radius Corner of each target.
--yeti-control-size Minimum size of each target.
--yeti-color-primary The default variant's colour, when data-variant is absent.
--yeti-color-primary-subtle The default variant's tint.
--yeti-color-primary-soft The default variant's soft stop.
--yeti-color-primary-strong The default variant's strong stop.
--yeti-color-primary-text The default variant's text colour.
--yeti-on-primary Text on the default variant's colour.
--yeti-text-md Text size when data-size is absent.
--yeti-space-sm The space step when data-size is absent; a target's inline padding follows it.
--yeti-space-xs Gap between targets.
--yeti-color-text-muted The span standing for skipped pages.
Internal tokens (may change between minor versions) - `--_yeti-variant` - `--_yeti-variant-subtle` - `--_yeti-on-variant` - `--_yeti-justify` - `--_yeti-size-text` - `--_yeti-variant-soft` - `--_yeti-variant-strong` - `--_yeti-variant-text` - `--_yeti-size-space`

Accessibility

  • Required attributes: aria-label or aria-labelledby
  • Put aria-label="Pagination" on the nav. The current page's link carries aria-current="page". Previous and Next carry rel="prev" and rel="next" and visible text or an aria-label; they are what remains when the row is narrow. Skipped pages are a span, not a link. Put role="list" on the ol.

Browser support

  • Used without guards: container size queries, :has()
  • Behind @supports: nothing

JavaScript

None. This component is CSS only.

Available since 7.0.0.