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

Basic Single-Select Filter Bar

The canonical form. Slot <mds-filter-item> children directly; the parent enforces exclusive selection in single mode - selecting one item deselects all others. Always provide value on each item so the mdsFilterChange event carries meaningful data.

<mds-filter label="Categoria">
  <mds-filter-item label="Tutti" value="all"></mds-filter-item>
  <mds-filter-item label="Notizie" value="news"></mds-filter-item>
  <mds-filter-item label="Comunicati" value="press" count="14"></mds-filter-item>
  <mds-filter-item label="Aggiornamenti" value="updates" count="3"></mds-filter-item>
</mds-filter>

Listening to Selection Changes

Listen to mdsFilterChange on the parent. The event detail carries value (comma-joined string of selected value attributes) and children (the NodeList of the items, for advanced inspection).

<mds-filter id="filter-stato" label="Stato">
  <mds-filter-item label="Bozza" value="draft"></mds-filter-item>
  <mds-filter-item label="Pubblicato" value="published"></mds-filter-item>
  <mds-filter-item label="Archiviato" value="archived"></mds-filter-item>
</mds-filter>

<script>
  document.getElementById('filter-stato').addEventListener('mdsFilterChange', (event) => {
    console.log('Filtro attivo:', event.detail.value);
  });
</script>

Multi-Select Filter Bar

Set multiple when filters are additive rather than mutually exclusive. All selected items stay active simultaneously; mdsFilterChange fires after each toggle.

<mds-filter label="Etichette" multiple>
  <mds-filter-item label="Urgente" value="urgent" count="2"></mds-filter-item>
  <mds-filter-item label="In revisione" value="review" count="7"></mds-filter-item>
  <mds-filter-item label="Completato" value="done" count="31"></mds-filter-item>
  <mds-filter-item label="Annullato" value="cancelled"></mds-filter-item>
</mds-filter>

Reset Button

Set reset to show a clear-all control whenever at least one item is active. The reset control is hidden when no filter is selected and becomes visible automatically when a selection is made. It is named in the page language (“Clear filters”) and emits mdsFilterChange with an empty value when it clears the selection.

<mds-filter label="Tipo documento" multiple reset>
  <mds-filter-item label="PDF" value="pdf" count="5"></mds-filter-item>
  <mds-filter-item label="Word" value="doc" count="12"></mds-filter-item>
  <mds-filter-item label="Immagine" value="image" count="8"></mds-filter-item>
</mds-filter>

Auto-Reset on Full Selection

Use auto-reset together with multiple when selecting all items is semantically identical to “no filter applied”. Once every item is selected, the component clears all selections automatically.

<mds-filter label="Priorita" multiple auto-reset>
  <mds-filter-item label="Alta" value="high"></mds-filter-item>
  <mds-filter-item label="Media" value="medium"></mds-filter-item>
  <mds-filter-item label="Bassa" value="low"></mds-filter-item>
</mds-filter>

Filter Item with Icon

Supply icon on individual <mds-filter-item> children to add a glyph alongside the label. The icon slug follows iconsauce conventions; the spoken name comes from label, or from the icon slug when no label is present (grid view for mi/baseline/grid-view).

<mds-filter label="Formato">
  <mds-filter-item label="Video" value="video" icon="mi/baseline/videocam"></mds-filter-item>
  <mds-filter-item label="Audio" value="audio" icon="mi/baseline/headset"></mds-filter-item>
  <mds-filter-item label="Testo" value="text" icon="mi/baseline/article"></mds-filter-item>
</mds-filter>

Pre-Selected Item

Set selected on a child at page load to reflect a filter that is already active (e.g. restored from a URL parameter or user preference). The parent picks up the initial state when it loads.

<mds-filter label="Periodo">
  <mds-filter-item label="Oggi" value="today"></mds-filter-item>
  <mds-filter-item label="Settimana corrente" value="week" selected></mds-filter-item>
  <mds-filter-item label="Mese corrente" value="month"></mds-filter-item>
</mds-filter>

Setting the Selection from the Application

When the filters live somewhere else - in the address, in a store, behind a “Clear filters” button outside the bar - set selected on the items: the bar follows as after the same clicks (single mode, reset button), without emitting mdsFilterChange. In a framework, bind selected on each item to the state.

<mds-filter id="status" label="Stato" reset>
  <mds-filter-item label="Nuove" value="new"></mds-filter-item>
  <mds-filter-item label="Aperte" value="open"></mds-filter-item>
  <mds-filter-item label="Chiuse" value="closed"></mds-filter-item>
</mds-filter>
<mds-button id="clear" label="Rimuovi i filtri" variant="dark" tone="text"></mds-button>

const items = [...document.querySelectorAll('#status mds-filter-item')];

// restore the filter from the address on load
const status = new URLSearchParams(location.search).get('status');
items.forEach((item) => {
  item.selected = item.value === status;
});

// clear it from a button outside the bar
document.querySelector('#clear').addEventListener('click', () => {
  items.forEach((item) => {
    item.selected = false;
  });
});

Disabled Item

Set disabled on individual <mds-filter-item> children to block them: a disabled item leaves the tab order, ignores clicks and keys, is announced as unavailable (aria-disabled) and is painted in the disabled text colour.

<mds-filter label="Stato pratica">
  <mds-filter-item label="Aperta" value="open" count="9"></mds-filter-item>
  <mds-filter-item label="In attesa" value="pending" count="2"></mds-filter-item>
  <mds-filter-item label="Chiusa" value="closed" disabled></mds-filter-item>
</mds-filter>

Styling Customization

Style the filter bar only through its documented --mds-filter-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) and the --magma-radius-* scale so dark mode, high-contrast modes and the corner geometry keep working.

.filtri-personalizzati mds-filter {
  --mds-filter-items-background: rgb(var(--magma-wash-strong));
  --mds-filter-items-background-active: rgb(var(--magma-accent-surface));
  --mds-filter-items-radius: var(--magma-radius-md);
  --mds-filter-items-gap: calc(var(--spacing) * 300);
  --mds-filter-wrapper-shadow-color: rgb(var(--magma-accent-border));
  --mds-filter-wrapper-shadow-opacity: 0.2;
}