Common incorrect uses of <mds-filter-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-filter-item> Outside <mds-filter>

<mds-filter-item> is a compound child component. Without its parent it has no selection management, no auto-scroll, and no mdsFilterChange aggregation. Always wrap it in <mds-filter>.

<!-- INCORRECT -->
<div class="my-filters">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
  <mds-filter-item label="Archiviato" value="archived"></mds-filter-item>
</div>

<!-- CORRECT -->
<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
  <mds-filter-item label="Archiviato" value="archived"></mds-filter-item>
</mds-filter>

Do Not Set selected="false" to Deselect

selected is a boolean prop: remove the attribute entirely to deselect, as for every boolean. The runtime happens to read the string "false" as false, but the attribute stays in the markup until the component renders, and HTML, [selected] selectors and hasAttribute() read a present attribute as set.

<!-- INCORRECT -->
<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active" selected="false"></mds-filter-item>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
</mds-filter>

Do Not Omit value

value is the machine-readable token the parent aggregates into mdsFilterChange. Without it the parent’s event payload is empty or meaningless for consumers - always provide a distinct, meaningful value.

<!-- INCORRECT -->
<mds-filter label="Priorita">
  <mds-filter-item label="Alta"></mds-filter-item>
  <mds-filter-item label="Bassa"></mds-filter-item>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Priorita">
  <mds-filter-item label="Alta" value="high"></mds-filter-item>
  <mds-filter-item label="Bassa" value="low"></mds-filter-item>
</mds-filter>

Do Not Slot Content Inside <mds-filter-item>

<mds-filter-item> has no publicly documented default or named slots. Icon, label, and count are all props. Slotting arbitrary HTML has no effect - use the dedicated props instead.

<!-- INCORRECT -->
<mds-filter label="Formato">
  <mds-filter-item value="pdf">
    <mds-icon name="mi/baseline/picture-as-pdf"></mds-icon>
    PDF
  </mds-filter-item>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Formato">
  <mds-filter-item icon="mi/baseline/picture-as-pdf" label="PDF" value="pdf"></mds-filter-item>
</mds-filter>

Do Not Listen for Native click Instead of mdsFilterItemSelect

The component handles its own toggle internally and emits mdsFilterItemSelect when selection changes. A native click listener added before the component has loaded runs before the internal toggle (listeners run in the order they were added), so it reads the old selected state.

<!-- INCORRECT -->
<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
</mds-filter>
<script>
  document.querySelector('mds-filter-item[value="active"]').addEventListener('click', (e) => {
    console.log('selected?', e.target.selected); // state not yet updated
  });
</script>

<!-- CORRECT -->
<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
</mds-filter>
<script>
  document.querySelector('mds-filter-item[value="active"]').addEventListener('mdsFilterItemSelect', (e) => {
    console.log('selected:', e.detail.selected);
  });
</script>

Do Not Customize via Undocumented Shadow Parts or Internal Selectors

The supported customization surface is the four --mds-filter-item-count-* CSS custom properties. Targeting shadow internals via ::part(), >>>, or other selectors couples code to the implementation and will break on minor releases.

/* INCORRECT */
mds-filter-item >>> .count {
  border-radius: 4px;
}
mds-filter-item::part(count) {
  background: red;
}

/* CORRECT */
mds-filter-item {
  --mds-filter-item-count-background-default: rgb(var(--magma-accent-surface-hover));
  --mds-filter-item-count-color-default: rgb(var(--magma-accent-fg));
}