Pagination

Page navigation. Unlike the other components, the page buttons are dynamic — Zag decides which page numbers and ellipses to show. You provide <template>s and stimulus-zag stamps them into the list as the page changes.

<nav
  data-controller="zag-pagination"
  data-part="root"
  data-zag-pagination-count-value="200"
  data-zag-pagination-page-size-value="20"
  class="flex items-center gap-1"
  aria-label="Pagination"
>
  <button
    data-part="prev-trigger"
    class="border-input bg-popover hover:bg-accent rounded-md border px-3 py-1.5 text-sm disabled:opacity-40"
  >
    Prev
  </button>

  <ul data-zag-pagination-target="list" class="flex items-center gap-1">
    <template data-zag-pagination-target="pageTemplate">
      <li>
        <button
          data-part="item"
          class="border-input bg-popover hover:bg-accent data-[selected]:border-primary data-[selected]:bg-primary data-[selected]:text-primary-foreground min-w-9 rounded-md border px-3 py-1.5 text-sm"
        ></button>
      </li>
    </template>
    <template data-zag-pagination-target="ellipsisTemplate">
      <li><span data-part="ellipsis" class="text-muted-foreground px-2">…</span></li>
    </template>
  </ul>

  <button
    data-part="next-trigger"
    class="border-input bg-popover hover:bg-accent rounded-md border px-3 py-1.5 text-sm disabled:opacity-40"
  >
    Next
  </button>
</nav>

Parts

root, prev-trigger, next-trigger, first-trigger, last-trigger, item, ellipsis.

Targets: list (where items render), pageTemplate, ellipsisTemplate.

Values

Attribute	Type	Default	Description
data-zag-pagination-count-value	Number	0	Total number of items.
data-zag-pagination-page-size-value	Number	10	Items per page.
data-zag-pagination-page-value	Number	1	Current page (also drives updates).
data-zag-pagination-sibling-count-value	Number	1	Page buttons shown around the current.

Events

Emits zag-pagination:change — detail is { page, pageSize }.

Programmatic control

page (getter), totalPages (getter), setPage(page), next(), previous().