Common incorrect uses of <mds-paginator>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Slot mds-paginator-item Manually

<mds-paginator> generates all its child items from the pages prop and accepts no slots. Manually added <mds-paginator-item> children are never rendered, so they have no effect.

<!-- INCORRECT -->
<mds-paginator pages="5">
  <mds-paginator-item selected>3</mds-paginator-item>
</mds-paginator>

<!-- CORRECT -->
<mds-paginator pages="5" current-page="3"></mds-paginator>

Do Not Use mds-paginator-item Outside mds-paginator

<mds-paginator-item> is an internal sub-part. Its disabled, selected, and icon props are managed exclusively by the parent. Using it standalone produces controls that look like page items but do nothing: the page logic lives in the parent.

<!-- INCORRECT -->
<mds-paginator-item>1</mds-paginator-item>
<mds-paginator-item selected>2</mds-paginator-item>

<!-- CORRECT -->
<mds-paginator pages="5" current-page="2"></mds-paginator>

Do Not Set pages to Zero to “Hide” the Paginator

When pages is 0 only the two arrows render, which is visually incomplete and confusing. To conditionally hide the paginator, remove it from the DOM entirely or set display: none on the host.

<!-- INCORRECT -->
<mds-paginator pages="0"></mds-paginator>

<!-- CORRECT: create the paginator only when there are pages -->
<div id="paginazione"></div>
<script>
  if (totalePagine > 0) {
    const pager = document.createElement('mds-paginator');
    pager.pages = totalePagine;
    document.getElementById('paginazione').append(pager);
  }
</script>

Do Not Listen for Native click to Detect Page Changes

A native click bubbles out of the shadow DOM for any click on the control, but it carries no page number. Use the documented mdsPaginatorChange event instead, which carries the selected page number in event.detail.page.

<!-- INCORRECT -->
<mds-paginator id="pager" pages="10"></mds-paginator>
<script>
  document.getElementById('pager').addEventListener('click', (e) => {
    // detail.page is undefined - this is the wrong event
    console.log(e.detail?.page);
  });
</script>

<!-- CORRECT -->
<mds-paginator id="pager" pages="10"></mds-paginator>
<script>
  document.getElementById('pager').addEventListener('mdsPaginatorChange', (e) => {
    console.log(e.detail.page);
  });
</script>

Do Not Pierce Shadow DOM to Style Items

Internal mds-paginator-item elements live in shadow DOM. Targeting them with >>>, /deep/, or unrecognised ::part() names breaks on any release. Use the documented --mds-paginator-* CSS custom properties on the host instead; the items themselves take no customization from outside (their --mds-paginator-item-* values are declared on each item).

/* INCORRECT */
mds-paginator >>> mds-paginator-item {
  border-radius: 4px;
}

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