Prototype Library

Pagination

Page navigation with a page-size selector, a derived range label, and first / prev / next / last controls. A Lit web component — page state and prev/next are real runtime behavior.

Inherited wc import '@esa/ecology/esa-pagination';

Preview

<esa-pagination total-items="237"></esa-pagination>

<script>
  const p = document.querySelector('esa-pagination');
  p.pageSizeOptions = [10, 25, 50, 100];
  p.addEventListener('pagechange', (e) => console.log(e.detail));
</script>

Variants

Compact form — hide the page-size selector and the first/last jump buttons for tighter footers.

<esa-pagination
  total-items="80"
  page-size="20"
  show-page-size-selector="false"
  show-first-last-buttons="false"
></esa-pagination>

States

Disabled — all controls are dimmed and inert.

<esa-pagination total-items="100" disabled></esa-pagination>

API

PropTypeDefaultDescription
total-items number 0 Total number of items across all pages; drives the range label and page count. Property: `totalItems`.
page-size number 25 Items per page. Changing it resets to page 0. Property: `pageSize`.
current-page number 0 Active page, zero-based. Property: `currentPage`.
page-size-options number[] [10, 25, 50, 100] Choices in the page-size selector. Array property — set in JS. Property: `pageSizeOptions`.
show-page-size-selector boolean true Toggles the "Items per page" selector. Property: `showPageSizeSelector`. On by default. Write `="false"` to turn it off — unusually for a boolean attribute, this one reads the value.
show-first-last-buttons boolean true Toggles the first / last jump buttons. Property: `showFirstLastButtons`. On by default. Write `="false"` to turn it off — unusually for a boolean attribute, this one reads the value.
disabled boolean false Dims and disables all controls. Reflected as an attribute.

Events

EventTypeDefaultDescription
pagechange CustomEvent — Fired when the page changes. detail: { page: number } (zero-based). Bubbles and composed.
pagesizechange CustomEvent — Fired when the page size changes; page also resets to 0. detail: { pageSize: number }. Bubbles and composed.
Binding these events from Angular

Every one of these is a CustomEvent, so the payload is on $event.detail — $event.target.value reads empty, with no error. The names are lowercase and Angular passes them to addEventListener verbatim, so camel-casing one means it never fires.

  • (pagechange)="onPagechange($event.detail)"
  • (pagesizechange)="onPagesizechange($event.detail)"

page-size-options is an array property — set it in JS, not as an attribute. The range label is derived as "start – end of total" ("0 of 0" when empty).

Accessibility

  • Wraps controls in role="navigation" with aria-label="Pagination".
  • Each control button has a descriptive aria-label (First / Previous / Next / Last page).
  • The page-size selector is a native labeled <select>.
  • Boundary buttons disable at the first/last page rather than wrapping.