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

Basic Filter Group

The canonical form. Place one or more <mds-filter-item> elements as direct children of <mds-filter>. Every item requires a label (the visible text) and a value (the machine-readable token emitted by the parent’s mdsFilterChange event).

<mds-filter label="Stato">
  <mds-filter-item label="Attivo" value="active"></mds-filter-item>
  <mds-filter-item label="In attesa" value="pending"></mds-filter-item>
  <mds-filter-item label="Archiviato" value="archived"></mds-filter-item>
</mds-filter>

Pre-selecting an Item on Load

Set selected on an item in the initial markup to make it active before any user interaction. The parent reads selected on mount and reflects the aggregated state correctly.

<mds-filter label="Categoria">
  <mds-filter-item label="Tutti" value="all" selected></mds-filter-item>
  <mds-filter-item label="Notizie" value="news"></mds-filter-item>
  <mds-filter-item label="Eventi" value="events"></mds-filter-item>
</mds-filter>

Count Badge

Pass a count string to show how many results each filter would yield. Use it when the number is meaningful to the user; omit it for purely categorical filters to keep the UI uncluttered.

<mds-filter label="Priorita">
  <mds-filter-item label="Alta" value="high" count="12"></mds-filter-item>
  <mds-filter-item label="Media" value="medium" count="34"></mds-filter-item>
  <mds-filter-item label="Bassa" value="low" count="5"></mds-filter-item>
</mds-filter>

Icon-Only Item

Omit label and provide only icon. Without a label the item is named after the last segment of the icon slug (grid view for mi/baseline/grid-view); an aria-label of your own takes its place and stays. Use a recognizable icon so the purpose is clear without text, and give each item an aria-label when the slug does not say what it filters.

<mds-filter label="Vista">
  <mds-filter-item aria-label="Griglia" icon="mi/baseline/grid-view" value="grid"></mds-filter-item>
  <mds-filter-item aria-label="Elenco" icon="mi/baseline/view-list" value="list"></mds-filter-item>
  <mds-filter-item aria-label="Mappa" icon="mi/baseline/map" value="map"></mds-filter-item>
</mds-filter>

Item with Icon and Label

Combine icon and label for a filter item that pairs a glyph with a text description.

<mds-filter label="Tipo documento">
  <mds-filter-item icon="mi/baseline/picture-as-pdf" label="PDF" value="pdf"></mds-filter-item>
  <mds-filter-item icon="mi/baseline/image" label="Immagini" value="image"></mds-filter-item>
  <mds-filter-item icon="mi/baseline/video-library" label="Video" value="video"></mds-filter-item>
</mds-filter>

Multiple Selection

Add multiple to <mds-filter> to allow several items to be selected at the same time. The parent aggregates the selected values into a comma-separated string and emits it via mdsFilterChange.

<mds-filter label="Settore" multiple>
  <mds-filter-item label="Sanita" value="health"></mds-filter-item>
  <mds-filter-item label="Istruzione" value="education"></mds-filter-item>
  <mds-filter-item label="Trasporti" value="transport"></mds-filter-item>
  <mds-filter-item label="Ambiente" value="environment"></mds-filter-item>
</mds-filter>

Listening for Selection Events

Listen to mdsFilterItemSelect on a single item for per-item reactions, or to mdsFilterChange on the parent for the aggregated selection. The event detail for mdsFilterItemSelect is { id: string, selected: boolean }.

<mds-filter id="tipo-filter" label="Tipo">
  <mds-filter-item label="Bozza" value="draft"></mds-filter-item>
  <mds-filter-item label="Pubblicato" value="published"></mds-filter-item>
</mds-filter>

<script>
  document.getElementById('tipo-filter').addEventListener('mdsFilterChange', (e) => {
    console.log('Valori selezionati:', e.detail.value);
  });
</script>

Reset Affordance

Add reset to <mds-filter> to show an automatic reset button when at least one item is active. The button is rendered by the parent internally - no extra <mds-filter-item> is needed - and named in the page language (“Clear filters”).

<mds-filter label="Regione" reset>
  <mds-filter-item label="Nord" value="north"></mds-filter-item>
  <mds-filter-item label="Centro" value="center"></mds-filter-item>
  <mds-filter-item label="Sud" value="south"></mds-filter-item>
</mds-filter>

CSS Custom Properties for the Count Badge

Customize the count badge colors through the four documented --mds-filter-item-count-* CSS custom properties. Set them on the host element or on a parent selector; use the semantic color roles via rgb(var(--magma-<role>)).

.priority-filter mds-filter-item {
  --mds-filter-item-count-background-default: rgb(var(--magma-wash-strong));
  --mds-filter-item-count-color-default: rgb(var(--magma-text-default));
  --mds-filter-item-count-background-selected: rgb(var(--magma-accent-emphasis));
  --mds-filter-item-count-color-selected: rgb(var(--magma-accent-on-emphasis));
}