Vanilla Breeze

pager-wc

Standalone pagination controls element targeting any [data-paged] container. The element form of the data-paged primitive. Mirrors VB's layout-* / data-layout-* element-attribute symmetry — pick the surface that fits the markup.

Overview

The <pager-wc> element is the element form of the data-paged primitive. Same engine, different surface. Authors choose:

  • Attribute form — data-paged on the container; controls render in place as siblings of the items.
  • Element form — <pager-wc target="#id"> anywhere on the page; controls live wherever you put the element.

This mirrors the framework-wide pattern: <layout-grid> + data-layout-min, <layout-stack> + data-gap, etc. Element-and-attribute symmetry covers all the cases — pick the one that fits the markup you already have.

When to reach for pager-wc

Use the element form when the items and the controls live in different parts of the layout:

  • Controls in a sticky header with items in the main column
  • Controls in a footer with items above
  • Multiple sets of controls (top + bottom) staying in sync
  • Controls in a sidebar driving a paginated main column

For the common in-place case (controls right after the items), use data-paged directly — no extra element required.

Attributes

AttributeTypeDefaultDescription
target string (CSS selector) — Preferred. CSS selector for the [data-paged] container.
for string (id) — HTML-form-style alternative to target: the bare ID of the target.
style enum: numbered · prev-next · load-more numbered Control style. infinite is intentionally unsupported — an IntersectionObserver sentinel doesn't make sense for decoupled controls.

Implicit target: if neither target nor for is set, <pager-wc> binds to the nearest preceding [data-paged] sibling. Useful for the common "items above, pager below" pattern with zero wiring.

Events

EventDetailNotes
pager-wc:navigate { page } Bubbles before the target processes the navigation. Use for analytics, scroll-restore, or transition hooks.

The target's own paged:change event fires from the data-paged engine after the slice updates — listen on the target itself for "after navigation" hooks.

Multi-instance sync

Two or more <pager-wc> elements pointing at the same target stay in sync automatically — each subscribes to the target's paged:change event and re-renders. No additional wiring needed.

Accessibility

  • Renders the same <nav aria-label="Pagination"> markup as data-paged — native <button>s, aria-current="page", ellipsis with aria-hidden.
  • If the target can't be found, the element renders a polite live-region note ("No paginated target found") instead of failing silently.

How it talks to the engine

The decoupled-control story is wired through three custom events on the target:

  • paged:change — fired by the engine after each render. <pager-wc> listens and re-renders its own controls.
  • paged:goto { page } — fired by <pager-wc> button clicks. The engine listens and navigates.
  • paged:loadmore — fired for the load-more button. Same pattern.

Any consumer can dispatch paged:goto on a [data-paged] container to drive navigation — <pager-wc> is just one possible source.
↑