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

Note: <mds-paginator-item> is an internal sub-part of mds-paginator. The idiomatic way to display page navigation is to use <mds-paginator> directly - it renders and manages all items automatically. The patterns below document the component’s surface to show how the parent assembles it.

Using mds-paginator (the normal case)

Render a paginator by setting pages and current-page on the parent. The parent creates one <mds-paginator-item> per page number plus the back and forward arrow items; you never instantiate them yourself.

<mds-paginator pages="12" current-page="1"></mds-paginator>

Listening for Page Changes

The page-change event is emitted by the parent <mds-paginator> as mdsPaginatorChange. Do not listen for click events on individual items.

<mds-paginator id="paginatore" pages="20" current-page="1"></mds-paginator>

<script>
  document.querySelector('#paginatore').addEventListener('mdsPaginatorChange', (e) => {
    console.log('Pagina selezionata:', e.detail.page);
  });
</script>

Numbered Page Item (text slot)

When icon is not set, the item renders the default slot content as the page number label. The slot expects a plain text string - no HTML elements or components.

<!-- Rendered internally by mds-paginator; shown here for reference only -->
<mds-paginator-item>7</mds-paginator-item>

Icon-Based Navigation Item

When icon is set, the item renders an icon instead of the text slot and is used for the back and forward arrow controls. The parent passes its own back and forward arrow icons, bundled in the component.

<!-- Rendered internally by mds-paginator; shown here for reference only -->
<mds-paginator-item icon="mi/baseline/arrow-back" disabled></mds-paginator-item>
<mds-paginator-item icon="mi/baseline/arrow-forward"></mds-paginator-item>

Selected and Disabled States

selected marks the current page and makes the item inert. disabled marks a navigation arrow as unavailable (e.g. back arrow on page 1) and also blocks activation. Both are boolean attributes that the parent manages.

<!-- Current page - selected, inert -->
<mds-paginator-item selected>3</mds-paginator-item>

<!-- Back arrow on page 1 - disabled, inert -->
<mds-paginator-item icon="mi/baseline/arrow-back" disabled></mds-paginator-item>

CSS Customization

The documented --mds-paginator-item-* CSS custom properties are declared on each item’s own host, so a value set on the parent mds-paginator host or on a containing selector does not inherit into the rendered items: the items cannot be restyled from outside. Customize the parent through its own --mds-paginator-background and --mds-paginator-scroll-behavior.

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