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

Basic Accordion

The canonical form. Place one or more mds-accordion-item elements as direct children. Each item requires a label for its always-visible header.

<mds-accordion>
  <mds-accordion-item label="Informazioni generali">
    <mds-text>Contenuto della prima sezione.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Requisiti tecnici">
    <mds-text>Contenuto della seconda sezione.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Contatti">
    <mds-text>Contenuto della terza sezione.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Pre-selected Item on Load

Set the selected attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).

<mds-accordion>
  <mds-accordion-item label="Panoramica" selected>
    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Dettagli">
    <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Multiple Selection Mode

Set multiple to allow any number of panels to be open at the same time. The mdsAccordionChange event then reports a comma-separated list of open indices.

<mds-accordion multiple>
  <mds-accordion-item label="Documentazione" selected>
    <mds-text>Scarica la guida utente in formato PDF.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Video tutorial" selected>
    <mds-text>Guarda i video di formazione nel portale.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="FAQ">
    <mds-text>Consulta le domande frequenti.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Mandatory Selection (Non-closable)

Set disable-close to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.

<mds-accordion disable-close>
  <mds-accordion-item label="Passaggio 1 - Dati anagrafici" selected>
    <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Passaggio 2 - Residenza">
    <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Passaggio 3 - Riepilogo">
    <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Heading Typography on Items

Set typography on each mds-accordion-item to align the header level with the document outline. Defaults to h5; use a heavier heading for more prominent section headers.

<mds-accordion>
  <mds-accordion-item label="Sezione principale" typography="h3">
    <mds-text>Contenuto della sezione principale.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Sottosezione" typography="h4">
    <mds-text>Contenuto della sottosezione.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Listening to the Change Event

Listen for mdsAccordionChange to react when the active panel changes. The event detail carries children (the full NodeList) and selected (a string index or comma-separated indices when multiple is set).

<mds-accordion id="faq-accordion">
  <mds-accordion-item label="Cos'e' Magma?">
    <mds-text>Magma e' il design system di Maggioli.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Come si installa?">
    <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>
  </mds-accordion-item>
</mds-accordion>

<script>
  document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {
    console.log('Pannello aperto:', event.detail.selected);
  });
</script>

Rich Slotted Content in Items

The default slot of each mds-accordion-item accepts text, HTML elements, and other Magma components - use this to build complex content panels.

<mds-accordion>
  <mds-accordion-item label="Dettagli del documento">
    <mds-text typography="label">Nome file</mds-text>
    <mds-text>Relazione_annuale_2024.pdf</mds-text>
    <mds-hr></mds-hr>
    <mds-text typography="label">Dimensione</mds-text>
    <mds-text>2,4 MB</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Azioni disponibili">
    <mds-button label="Scarica" icon="mi/baseline/download" variant="primary"></mds-button>
    <mds-button label="Condividi" icon="mi/baseline/share" variant="primary" tone="outline"></mds-button>
  </mds-accordion-item>
</mds-accordion>

Styling Customization

Style the accordion only through its documented --mds-accordion-* CSS custom properties. The properties cascade into all child mds-accordion-item elements from the host.

.custom-faq mds-accordion {
  --mds-accordion-border-color: rgb(var(--magma-accent-border));
  --mds-accordion-color: rgb(var(--magma-text-default));
  --mds-accordion-description-color: rgb(var(--magma-text-muted));
  --mds-accordion-duration: 200ms;
  --mds-accordion-padding-selected: calc(var(--spacing) * 600) 0 calc(var(--spacing) * 800) 0;
  --mds-accordion-padding-unselected: calc(var(--spacing) * 400) 0;
}