Pagination

Splits large data sets across numbered pages with previous and next navigation.

When to use

✓Use when a data set has more items than can be shown on a single screen (typically more than 25–50 rows).
✓Use on search results, data tables, and catalogue grids where the user may want to jump to a specific page.
✓Use with a per-page selector so users can control the page size.
✓Place pagination at the bottom of the list it controls, ideally with a result count summary above.
✓Prefer pagination over infinite scroll when the user needs to share, bookmark, or return to a specific position.

Don't

✕Don't use pagination for fewer than 2 pages — hide the component entirely.
✕Don't use pagination for continuous content such as feeds, timelines, or chat — use infinite scroll instead.
✕Don't place pagination above the list; users need to scroll through results before navigating.
✕Don't update the URL without preserving pagination state — the back button must restore the correct page.
✕Don't reset the active page to 1 when filtering unless the filter genuinely invalidates the current page.

Controlled pattern

diwa-pagination is semi-controlled: it mutates its own active-page prop on user interaction and simultaneously emits an update event carrying { page, previousPage }. Listen to update to sync external state or fire a data-fetch.

// Vanilla JS
const el = document.querySelector('diwa-pagination');
el.addEventListener('update', (e) => {
  const { page, previousPage } = e.detail;
  fetchPage(page);
});

// React — lowercase onupdate (React 19 custom element mapping)
<diwa-pagination
  total-items-count={totalCount}
  items-per-page={pageSize}
  active-page={currentPage}
  onupdate={(e) => {
    setCurrentPage(e.detail.page);
    fetchPage(e.detail.page);
  }}
/>

Hiding the last-page shortcut

By default the last page number is always shown so users know the extent of the data set. Set show-last-page="false" when the total count is unknown (cursor-based pagination) or when showing the last page is not meaningful.

<!-- When the total count is known — show last page (default) -->
<diwa-pagination total-items-count="1000" items-per-page="25" />

<!-- When the total count is unknown / streaming -->
<diwa-pagination total-items-count="9999" items-per-page="25" show-last-page="false" />

Localisation

Override the default aria-label strings via the intl prop. This is a plain object — pass it as a JavaScript reference rather than a JSON string attribute.

// React / Stencil JSX
<diwa-pagination
  intl={{ root: 'Seitennavigation', prev: 'Vorherige Seite', next: 'Nächste Seite', page: 'Seite' }}
  total-items-count={500}
  items-per-page={25}
/>

// Vanilla JS — assign the property directly (not via setAttribute)
const el = document.querySelector('diwa-pagination');
el.intl = { root: 'Navigation', prev: 'Précédent', next: 'Suivant', page: 'Page' };