Pagination

hc-pagination is a <nav> containing a flat list of page links. The current page is marked with aria-current="page" — that single attribute drives both the visual state and the assistive-tech signal.

Basic HTML

<nav class="hc-pagination" aria-label="Pagination">
  <a class="hc-pagination__item" aria-disabled="true">‹ Prev</a>
  <a class="hc-pagination__item" href="?page=1">1</a>
  <a class="hc-pagination__item" aria-current="page" href="?page=2">2</a>
  <a class="hc-pagination__item" href="?page=3">3</a>
  <a class="hc-pagination__item" href="?page=4">4</a>
  <a class="hc-pagination__item" href="?page=3">Next ›</a>
</nav>

States

aria-current="page" — the current page. Visually filled, not clickable (pointer-events disabled).
aria-disabled="true" — applied to the prev/next link when at the boundary. Also omit its href (as the examples do): the CSS only removes pointer events, so an anchor that keeps an href still activates with Enter. An <a> without href is a non-interactive placeholder — unfocusable and skipped by assistive tech, which is exactly right at a boundary.

The component never relies on plain disabled for anchors because anchors do not support that attribute. aria-disabled plus a template that drops the href at the boundary is the correct pattern; the CSS does the rest.

htmx usage

Page links can drive an htmx swap of the surrounding region.

<div id="orders">
  <table class="hc-table">…</table>

  <nav class="hc-pagination" aria-label="Pagination">
    <a class="hc-pagination__item" href="/orders?page=1"
       data-hx-get="/orders?page=1"
       data-hx-target="#orders"
       data-hx-swap="outerHTML"
       data-hx-push-url="true">1</a>
    <a class="hc-pagination__item" aria-current="page"
       href="/orders?page=2">2</a>
    …
  </nav>
</div>

data-hx-push-url="true" updates the address bar so deep links and the browser’s back button work. The server returns the whole #orders region — the table plus a pagination whose aria-current and boundary states have moved; the datagrid-pager recipe pins the full contract.

Accessibility

The wrapper is a real <nav> with an explicit aria-label.
The current item uses aria-current="page" — screen readers announce “current page” automatically.
Anchors stay anchors. The href for the current page is harmless (the CSS disables pointer events) but it makes the markup work without JavaScript and helps users bookmark the current view.

Theming tokens

Token path	Purpose
`pagination.gap`	Gap between items.
`pagination.item-size`	Minimum item size.
`pagination.padding-x`	Inline padding.
`pagination.radius`	Border radius.
`pagination.font-size` / `font-weight`	Typography.
`pagination.bg` / `-fg` / `-border`	Idle item colors.
`pagination.hover-bg`	Hover background.
`pagination.current-bg` / `-fg` / `-border`	Current item colors.
`pagination.disabled-fg`	Disabled link color.

CSS variables

Show the generated CSS variables

--hc-pagination-gap | -item-size | -padding-x | -radius
--hc-pagination-font-size | -font-weight
--hc-pagination-bg | -fg | -border
--hc-pagination-hover-bg
--hc-pagination-current-bg | -current-fg | -current-border
--hc-pagination-disabled-fg

Table — the usual host for pagination.