Common incorrect uses of <mds-filter>. 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 Arbitrary Elements Instead of mds-filter-item

The default slot accepts only <mds-filter-item> elements. The parent wires its coordination logic - exclusive selection, scroll-centering, value aggregation - by querying for mds-filter-item children. Slotting plain buttons, spans, or any other element breaks all of that coordination.

<!-- INCORRECT -->
<mds-filter label="Tipo">
  <button>Notizie</button>
  <button>Comunicati</button>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Tipo">
  <mds-filter-item label="Notizie" value="news"></mds-filter-item>
  <mds-filter-item label="Comunicati" value="press"></mds-filter-item>
</mds-filter>

Do Not Use mds-filter-item Outside mds-filter

<mds-filter-item> communicates state upward via the mdsFilterItemSelect event, which <mds-filter> listens for internally. Used standalone, the item has no parent to coordinate selection, no auto-scroll, and no combined mdsFilterChange output.

<!-- INCORRECT -->
<div class="my-filter-bar">
  <mds-filter-item label="Tutti" value="all"></mds-filter-item>
  <mds-filter-item label="Attivi" value="active"></mds-filter-item>
</div>

<!-- CORRECT -->
<mds-filter>
  <mds-filter-item label="Tutti" value="all"></mds-filter-item>
  <mds-filter-item label="Attivi" value="active"></mds-filter-item>
</mds-filter>

Do Not Listen to Native change Instead of mdsFilterChange

<mds-filter> emits the documented mdsFilterChange custom event. It contains no native form control, so no change or input event is ever fired; listening for them produces no result.

<!-- INCORRECT -->
<mds-filter id="f" label="Stato">
  <mds-filter-item label="Aperto" value="open"></mds-filter-item>
</mds-filter>
<script>
  document.getElementById('f').addEventListener('change', handler);
</script>

<!-- CORRECT -->
<mds-filter id="f" label="Stato">
  <mds-filter-item label="Aperto" value="open"></mds-filter-item>
</mds-filter>
<script>
  document.getElementById('f').addEventListener('mdsFilterChange', handler);
</script>

Do Not Set Boolean Props to the String "false"

auto-reset, multiple, and reset are boolean attributes: remove the attribute entirely to deactivate it, 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, [multiple] selectors and hasAttribute() read a present attribute as set.

<!-- INCORRECT -->
<mds-filter multiple="false" reset="false" label="Tipo">
  <mds-filter-item label="Tutti" value="all"></mds-filter-item>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Tipo">
  <mds-filter-item label="Tutti" value="all"></mds-filter-item>
</mds-filter>

Do Not Use auto-reset Without multiple

auto-reset is meaningful only in multiple mode - it triggers when all items are simultaneously selected. In single-select mode only one item can ever be active, so the “all selected” condition is never reached and auto-reset has no effect.

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

<!-- CORRECT -->
<mds-filter multiple auto-reset 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 Omit value on mds-filter-item

The mdsFilterChange event’s value field is a comma-joined string of the selected items’ value attributes. Items without a value contribute an empty string to the output, making the combined value ambiguous and hard to parse in application code.

<!-- INCORRECT -->
<mds-filter label="Formato">
  <mds-filter-item label="PDF"></mds-filter-item>
  <mds-filter-item label="Word"></mds-filter-item>
</mds-filter>

<!-- CORRECT -->
<mds-filter label="Formato">
  <mds-filter-item label="PDF" value="pdf"></mds-filter-item>
  <mds-filter-item label="Word" value="doc"></mds-filter-item>
</mds-filter>

Do Not Customize Via Undocumented Shadow Selectors

The supported customization surface for <mds-filter> is the documented --mds-filter-* CSS custom properties. Piercing the shadow DOM via >>> or undocumented ::part() names couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-filter >>> .items {
  background: white;
}
mds-filter::part(items-wrapper) {
  border: 2px solid red;
}

/* CORRECT */
mds-filter {
  --mds-filter-items-background: rgb(var(--magma-wash-strong));
  --mds-filter-wrapper-shadow-color: rgb(var(--magma-accent-border));
}