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

Basic List

The canonical form. Place <mds-list-item> children directly inside <mds-list>. Each item renders a leading bullet glyph (the default list-dot icon) and the slotted text.

<mds-list>
  <mds-list-item>Rinnova la licenza annuale</mds-list-item>
  <mds-list-item>Verifica i dati di fatturazione</mds-list-item>
  <mds-list-item>Scarica la ricevuta in PDF</mds-list-item>
</mds-list>

Overriding the Item Icon

Pass an icon slug to <mds-list-item> via the icon prop to replace the default bullet with a meaningful glyph. Leave the prop unset to keep the standard dot.

<mds-list>
  <mds-list-item icon="mi/baseline/check-circle">Profilo aggiornato</mds-list-item>
  <mds-list-item icon="mi/baseline/check-circle">Password modificata</mds-list-item>
  <mds-list-item icon="mi/baseline/pending">Verifica email in attesa</mds-list-item>
</mds-list>

Choosing the Typography Scale

Use the typography prop on each <mds-list-item> to match the visual density of the surrounding content. The default is detail; use paragraph for body-copy contexts and caption or tip for compact secondary lists.

<!-- Body-copy density - long paragraphs nearby -->
<mds-list>
  <mds-list-item typography="paragraph">Seleziona il piano adatto alle tue esigenze</mds-list-item>
  <mds-list-item typography="paragraph">Inserisci i dati di pagamento</mds-list-item>
  <mds-list-item typography="paragraph">Conferma l'ordine e ricevi la ricevuta</mds-list-item>
</mds-list>

<!-- Compact secondary list -->
<mds-list>
  <mds-list-item typography="caption">Aggiornato il 01/06/2026</mds-list-item>
  <mds-list-item typography="caption">Versione 3.2.1</mds-list-item>
</mds-list>

Reading Variant for Long-Form Content

Set variant="read" when list items appear inside a reading-optimized context (article, tutorial, legal text). Use the default variant="info" for compact informational lists.

<mds-list>
  <mds-list-item typography="paragraph" variant="read">
    Il servizio e' disponibile per tutti gli enti pubblici italiani
  </mds-list-item>
  <mds-list-item typography="paragraph" variant="read">
    L'accesso avviene tramite credenziali SPID o CIE
  </mds-list-item>
  <mds-list-item typography="paragraph" variant="read">
    I dati sono trattati in conformita' al GDPR
  </mds-list-item>
</mds-list>

Mixed Icon and Default Bullet in the Same List

You can mix items with an explicit icon and items that fall back to the default bullet within the same <mds-list>. Each item is independent.

<mds-list>
  <mds-list-item icon="mi/baseline/warning">Modulo non compilato</mds-list-item>
  <mds-list-item>Campo facoltativo ignorato</mds-list-item>
  <mds-list-item icon="mi/baseline/error">Firma digitale mancante</mds-list-item>
</mds-list>

Styling Customization via CSS Custom Property

Adjust icon spacing through the documented --mds-list-item-icon-margin CSS custom property. Set it on the <mds-list-item> host or on a parent selector; use Magma spacing tokens.

.sidebar-checklist mds-list-item {
  --mds-list-item-icon-margin: 0 calc(var(--spacing) * 300) 0 0;
}

Shadow Part Customization

Reach the icon or text nodes through the documented ::part(icon) and ::part(text) parts of <mds-list-item> when CSS custom properties are insufficient. Do not pierce the shadow DOM via >>> or undocumented selectors.

/* Tint the leading icon of every item in a warning context */
.alert-list mds-list-item::part(icon) {
  fill: rgb(var(--magma-warning-fg));
}