Pagination, one file.

API reference

The complete Pagination API — constructor, every option, instance methods, statics, events, declarative attributes, theming and accessibility.

Constructor & usage

new Pagination(target, options?)     // → instance
Pagination.create(target, options?)  // same as new

target is a selector string or an element — the <nav> of real buttons is rendered inside it. Give it either an item count (total + perPage) or the page count directly (pages, which takes precedence). Constructing on an element that already holds an instance destroys the old one first; the initial page is clamped and never fires onChange. A missing target throws; without a DOM (SSR) the constructor returns an inert no-op instance.

const pager = new Pagination('#pager', {
  total: 97,               // 97 items, 10 per page → 10 pages
  onChange: (page) => loadPage(page)
})

Options

Every key of Pagination.defaults, with its default value.

The labels object

Methods

Statics & helpers

Events & callbacks

Two channels report every real page move (a setPage to the same page, an initial clamp, or {silent: true} fire neither):

• onChange(page, pagination) — the option callback.
• pagination:change — a bubbling CustomEvent dispatched from the target element with detail: { page, pagination }.

document.getElementById('pager').addEventListener('pagination:change', (e) => {
  console.log(e.detail.page)        // the new page
  console.log(e.detail.pagination)  // the instance
})

Declarative init

Add data-vpn to a container — instances are built on DOMContentLoaded (or call Pagination.autoInit(root) after inserting markup). Listen for pagination:change on the container to react.

<div data-vpn data-total="97" data-per-page="10" data-show-jump></div>

Theming

Auto light/dark with the family's resolution order: <html data-theme> / data-bs-theme / .dark class → prefers-color-scheme, re-resolved live. Pin one instance with theme: 'dark'. All colors are CSS custom properties on .vpn:

.vpn {
  --vpn-accent: #b45309;   /* current page, focus rings */
  --vpn-text: …; --vpn-muted: …; --vpn-faint: …; --vpn-bg: …;
  --vpn-on-accent: …;      /* text on the current-page button */
  --vpn-radius: 8px; --vpn-font: …;
}

With the VC core loaded, VC.config({ accent: '#b45309' }) themes the pager and every other family component in one call. The nav renders as class="vpn vc1"; structural rules ship salted so host design systems can't override it, while the unsalted --vpn-* variable definitions keep page overrides working. Change the token with Pagination.salt = 'acme' (or false) before the first instance.

Headless: pass styles: false (per instance, or via Pagination.defaults) and no CSS is injected — you keep the full behavior (windowing, clamping, ARIA, keyboard) and style this markup contract yourself (Pagination.css is the reference stylesheet as a string):

nav.vpn[aria-label="Pagination"][data-theme="dark"]
  .vpn-total                      ← only when showTotal (total mode)
  button.vpn-btn.vpn-prev         ← disabled on page 1
  .vpn-pages                      ← or .vpn-status[aria-live] when compact
    button.vpn-btn[data-page]     ← [aria-current="page"] on the current one
    .vpn-gap                      ← the … separators
  button.vpn-btn.vpn-next         ← disabled on the last page
  label.vpn-jump > input          ← only when showJump

Accessibility

• Renders inside <nav aria-label="Pagination">; every page is a real <button>, so keyboard access is native (Tab + Enter/Space) — no custom key handling to learn.
• The current page carries aria-current="page" and ignores clicks; prev/next carry full aria-labels (their arrow glyphs are aria-hidden) and disable themselves at the ends; ellipses are inert aria-hidden separators.
• The strip keeps a constant item count while paging — the sibling window shifts inward near the edges instead of shrinking, so nothing jumps around under the pointer, and a gap that would hide only a single page becomes that page. If focus was inside the strip when it re-renders, focus is handed to the new current-page button.
• In compact mode the 3 / 12 readout is an aria-live="polite" region, so page flips are announced.
• The jump field is a <label>-wrapped number input; Enter jumps to the clamped page and never submits a surrounding form. Reduced motion is respected.

Headless mode

With styles: false Pagination injects no CSS at all — the full behavior (windowing, clamping, callbacks), native keyboard access, the ARIA contract and the stable .vpn-* class hooks all remain; you bring the stylesheet. The demos below each run in their own <iframe>: the styled examples above have already injected the component stylesheet into this page, so only a separate, clean document can show what headless truly looks like.

new Pagination('#pager', {
  total: 97, page: 3,
  showTotal: true,
  styles: false,   // ← zero CSS injected
  onChange: function (p) { /* … */ }
})

<style type="text/tailwindcss">
  .vpn        { @apply flex flex-wrap items-center gap-1.5; }
  .vpn-total  { @apply mr-2 text-xs font-medium text-slate-500; }
  .vpn-pages  { @apply flex items-center gap-1.5; }
  .vpn-btn    { @apply h-9 min-w-9 cursor-pointer rounded-full border-0
                bg-white px-3 text-sm font-semibold text-slate-600 shadow-sm
                ring-1 ring-slate-200 hover:bg-sky-50 hover:text-sky-700
                hover:ring-sky-300 disabled:cursor-not-allowed
                disabled:opacity-40; }
  .vpn-btn[aria-current="page"] { @apply bg-sky-600 text-white ring-sky-600
                shadow-md shadow-sky-200; }
  .vpn-gap    { @apply px-1 text-slate-400; }
  .vpn-jump   { @apply ml-2 flex items-center gap-1.5 text-xs text-slate-500; }
  .vpn-jump input { @apply w-14 rounded-lg border-0 px-2 py-1.5 text-sm
                ring-1 ring-slate-200 outline-none focus:ring-2
                focus:ring-sky-500; }
</style>