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.
page-size number 25 Items per page. Changing it resets to page 0.
current-page number 0 Active page, zero-based.
page-size-options number[] [10, 25, 50, 100] Choices in the page-size selector. Array property — set in JS.
show-page-size-selector boolean true Toggles the "Items per page" selector.
show-first-last-buttons boolean true Toggles the first / last jump buttons.
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.

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.