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

Basic Disclosure Block

The minimal form: a title slot for the always-visible header and a default slot for the collapsible body. Use mds-text in both slots so typography tokens are applied consistently.

<mds-details>
  <mds-text typography="h6" slot="title">Descrizione del progetto</mds-text>
  <mds-text typography="detail">
    Questa sezione raccoglie le informazioni principali relative all'ambito e agli obiettivi del
    progetto.
  </mds-text>
</mds-details>

Pre-expanded State via opened

Pass the opened boolean attribute to expand the block on first render. User toggles do not update it: read the state from mdsDetailsChange.

<mds-details opened>
  <mds-text typography="h6" slot="title">Note operative</mds-text>
  <mds-text typography="paragraph">
    Le note operative sono visibili fin dal caricamento della pagina per garantire una lettura
    immediata.
  </mds-text>
</mds-details>

Leading Icon via the icon Slot

Place an mds-icon in the icon slot to add a leading glyph that also acts as a toggle. The icon area auto-hides when the slot is empty, so leaving it out does not leave an empty gap.

<mds-details>
  <mds-icon slot="icon" name="mi/baseline/info"></mds-icon>
  <mds-text typography="h6" slot="title">Requisiti di accesso</mds-text>
  <mds-text typography="detail">
    Per accedere al servizio e necessario disporre di credenziali SPID di livello 2 o superiore.
  </mds-text>
</mds-details>

Action Button via the action Slot

The action slot sits at the bottom of the expandable content region. Use mds-button (recommended) for the primary action tied to the disclosed content.

<mds-details>
  <mds-icon slot="icon" name="mi/baseline/check-circle"></mds-icon>
  <mds-text typography="h6" slot="title">Modulistica richiesta</mds-text>
  <mds-text typography="detail">
    Scarica e compila il modulo A3 prima di procedere con la richiesta.
  </mds-text>
  <mds-button slot="action" size="sm" variant="primary" tone="outline" label="Scarica il modulo"></mds-button>
</mds-details>

Listening to Toggle Events

Subscribe to mdsDetailsChange to react to open/close transitions. The event detail carries the new boolean state. Do not listen for native click on the host.

<mds-details id="faq-1">
  <mds-text typography="h6" slot="title">Come posso rinnovare il contratto?</mds-text>
  <mds-text typography="detail">
    Il rinnovo puo essere effettuato online dall'area personale almeno 30 giorni prima della
    scadenza.
  </mds-text>
</mds-details>

<script>
  document.getElementById('faq-1').addEventListener('mdsDetailsChange', (event) => {
    console.log('Stato apertura:', event.detail); // true | false
  });
</script>

Programmatic Control

Assign the opened property to drive the disclosure from code - for example to expand all items at once or to implement accordion logic manually. User toggles do not write opened back, so assigning the value it already holds does nothing: a block the user closed after an opened = true stays closed until opened goes through false.

<mds-details id="step-1">
  <mds-text typography="h6" slot="title">Passo 1: Verifica dei dati</mds-text>
  <mds-text typography="detail">
    Controlla che tutti i dati anagrafici siano corretti prima di procedere.
  </mds-text>
</mds-details>

<mds-button id="expand-btn" label="Espandi tutti" variant="primary" tone="text"></mds-button>

<script>
  document.getElementById('expand-btn').addEventListener('click', () => {
    document.querySelectorAll('mds-details').forEach((el) => {
      el.opened = true;
    });
  });
</script>

CSS Customization

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

.custom-faq mds-details {
  --mds-details-duration: 500ms;
  --mds-details-icon-color: rgb(var(--magma-accent-emphasis));
  --mds-details-helper-icon-color: rgb(var(--magma-text-subtle));
}

Styling Shadow Parts

When CSS custom properties are not sufficient, use the documented shadow ::part() names: header, title, and content. Do not target undocumented internals.

/* Increase header padding for a spacious FAQ layout */
.faq-section mds-details::part(header) {
  padding: calc(var(--spacing) * 300) 0;
}

/* Give the title extra weight */
.faq-section mds-details::part(title) {
  font-weight: 600;
}