Correct and idiomatic ways to use the <mds-list-item> 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 with Default Bullet

The canonical form. Place one or more <mds-list-item> elements as direct children of <mds-list>. Text content goes in the default slot. When no icon is provided the component renders the built-in list-dot glyph automatically.

<mds-list>
  <mds-list-item>Pane</mds-list-item>
  <mds-list-item>Acqua</mds-list-item>
  <mds-list-item>Pasta</mds-list-item>
</mds-list>

Typography Scale

Use the typography prop to match the text density of the surrounding content. The default is detail; switch to paragraph for body-text contexts or caption / tip for fine-print lists.

<mds-list>
  <!-- Body-text list -->
  <mds-list-item typography="paragraph">Seleziona un elemento dalla lista</mds-list-item>
  <mds-list-item typography="paragraph">Conferma la scelta effettuata</mds-list-item>
  <mds-list-item typography="paragraph">Salva le modifiche apportate</mds-list-item>
</mds-list>

<mds-list>
  <!-- Fine-print annotation list -->
  <mds-list-item typography="caption">I campi contrassegnati sono obbligatori</mds-list-item>
  <mds-list-item typography="caption">La password deve contenere almeno 8 caratteri</mds-list-item>
</mds-list>

Reading Variant

Use variant="read" for long-form reading contexts (articles, documentation); keep the default variant="info" for compact informational lists in UI panels.

<!-- Long-form reading context -->
<mds-list>
  <mds-list-item typography="paragraph" variant="read">
    Il servizio e disponibile dal lunedi al venerdi, dalle 9 alle 18.
  </mds-list-item>
  <mds-list-item typography="paragraph" variant="read">
    Per assistenza urgente contattare il numero verde dedicato.
  </mds-list-item>
</mds-list>

Custom Leading Icon

Supply an icon slug via the icon prop to replace the default bullet with a meaningful glyph. Use this when each entry maps to a distinct category or action.

<mds-list>
  <mds-list-item icon="mi/baseline/check-circle">Account verificato</mds-list-item>
  <mds-list-item icon="mi/baseline/lock">Accesso sicuro attivato</mds-list-item>
  <mds-list-item icon="mi/baseline/notifications">Notifiche abilitate</mds-list-item>
</mds-list>

Uniform Icon Across All Items

When every item shares the same icon - for example a checklist or a feature list - set the same icon on each item for visual consistency.

<mds-list>
  <mds-list-item icon="mi/baseline/check">Supporto multilingua incluso</mds-list-item>
  <mds-list-item icon="mi/baseline/check">Aggiornamenti automatici</mds-list-item>
  <mds-list-item icon="mi/baseline/check">Assistenza prioritaria 24/7</mds-list-item>
</mds-list>

Muted List

The items take the colour of their container. When a list is secondary information (an address, a list of contacts under a title), give the muted role to <mds-list> or to its container rather than to each item.

<mds-list class="text-fg-muted">
  <mds-list-item>Via Carlo Farini 1, Santarcangelo di Romagna</mds-list-item>
  <mds-list-item>0541 628111</mds-list-item>
</mds-list>

Styling Customization via CSS Custom Property

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

.compact-list mds-list-item {
  --mds-list-item-icon-margin: 0 calc(var(--spacing) * 100) 0 0;
}

Styling the Icon Part

Use the documented ::part(icon) surface to tint or resize the leading icon. Prefer Magma color tokens to keep dark-mode compatibility.

.status-list mds-list-item::part(icon) {
  fill: rgb(var(--magma-success-fg));
}