Common incorrect uses of <mds-paginator-item>. 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 Use mds-paginator-item Standalone

<mds-paginator-item> is an internal sub-part rendered exclusively by <mds-paginator>. It has no standalone meaning; it relies on the parent to supply state (selected, disabled) and to handle page logic and the mdsPaginatorChange event.

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

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

Do Not Put HTML in the Default Slot

The default slot accepts a plain text string - the page number. Nested elements are not supported and break the item’s layout.

<!-- INCORRECT -->
<mds-paginator-item>
  <strong>5</strong>
</mds-paginator-item>

<!-- CORRECT -->
<mds-paginator-item>5</mds-paginator-item>

Do Not Set selected or disabled From Consumer Code

Both selected and disabled are driven by the parent paginator based on currentPage and page boundaries. Setting them manually from consumer code creates state conflicts with the parent’s rendering logic.

<!-- INCORRECT - consumer forcing selected state -->
<mds-paginator pages="10" current-page="3">
  <!-- attempting to override individual item state externally -->
</mds-paginator>
<script>
  document.querySelector('mds-paginator')
    .shadowRoot.querySelectorAll('mds-paginator-item')[2]
    .setAttribute('selected', '');
</script>

<!-- CORRECT - drive state through the parent prop -->
<mds-paginator pages="10" current-page="3"></mds-paginator>

Do Not Listen for Click Events on Items

Individual item clicks are handled internally by <mds-paginator>. Listening for click on items reaches into shadow DOM and bypasses the parent’s page validation and scroll logic. Use the documented mdsPaginatorChange event on the parent.

<!-- INCORRECT -->
<mds-paginator id="pag" pages="10" current-page="1"></mds-paginator>
<script>
  document.querySelector('#pag').shadowRoot
    .querySelectorAll('mds-paginator-item')
    .forEach((item) => item.addEventListener('click', handleClick));
</script>

<!-- CORRECT -->
<mds-paginator id="pag" pages="10" current-page="1"></mds-paginator>
<script>
  document.querySelector('#pag').addEventListener('mdsPaginatorChange', (e) => {
    console.log('Pagina:', e.detail.page);
  });
</script>

Do Not Pierce Shadow DOM to Style Items

From outside, the supported customization surface is the parent’s --mds-paginator-* CSS custom properties: the items declare their --mds-paginator-item-* values on their own host, so a value set on mds-paginator does not reach them. Targeting internals via ::part(), >>>, or undocumented selectors couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-paginator-item >>> .text {
  font-weight: 900;
}

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