Correct and idiomatic ways to use the <mds-paginator> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Basic Paginator

Provide pages with the total number of pages. The component renders all items and the previous/next arrows automatically. The pages prop is all that is required for a working paginator.

<mds-paginator pages="20"></mds-paginator>

Starting on a Specific Page

Set current-page to pre-select an initial page. On load the component emits mdsPaginatorChange and scrolls the strip to center the active item.

<mds-paginator pages="32" current-page="16"></mds-paginator>

Listening to Page Changes

Listen for mdsPaginatorChange to react to navigation. The event detail carries { page, caller } where page is the newly selected page number and caller is the mds-paginator-item that triggered the change.

<mds-paginator id="pager" pages="10"></mds-paginator>

<script>
  document.getElementById('pager').addEventListener('mdsPaginatorChange', (e) => {
    const nuovaPagina = e.detail.page;
    // Aggiorna la tabella o la lista con i dati della nuova pagina
    caricaDati(nuovaPagina);
  });
</script>

Controlled Navigation from Outside

Write current-page programmatically to drive the paginator from application state - for example when a search resets pagination to page 1.

<mds-paginator id="pager" pages="15" current-page="1"></mds-paginator>

<script>
  function resettaPaginazione() {
    document.getElementById('pager').currentPage = 1;
  }
</script>

Single-Page and Two-Page Edge Cases

When pages is 1 only the first/last item and the arrows appear (the scrollable strip is omitted). When pages is 2 both the first and last items render without the strip. Both are valid states - pass the real page count without special-casing.

<!-- Una sola pagina: solo gli arrow e la pagina 1 -->
<mds-paginator pages="1"></mds-paginator>

<!-- Due pagine: pagina 1 e pagina 2, nessuna strip -->
<mds-paginator pages="2"></mds-paginator>

Styling the Page Strip Background

Override --mds-paginator-background on the host to change the background of the scrollable pages area. Use a Magma color token wrapped in rgb(var(...)) so dark mode keeps working.

.mia-tabella mds-paginator {
  --mds-paginator-background: rgb(var(--magma-wash-strong));
}

Disabling Scroll Animation

Set --mds-paginator-scroll-behavior to auto to remove the animated scroll when jumping between pages - useful for contexts that already honour prefers-reduced-motion at application level.

.stampa mds-paginator {
  --mds-paginator-scroll-behavior: auto;
}

Styling Individual Items

The items cannot be restyled from outside. The child mds-paginator-item declares its --mds-paginator-item-* custom properties on its own host, so a value set on the mds-paginator host or a parent selector does not reach the shadow-rendered items, and the paginator exposes no shadow parts. Customize the paginator through --mds-paginator-background and --mds-paginator-scroll-behavior only (see the two patterns above).