Correct and idiomatic ways to use the <mds-accordion-item> 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 of <mds-accordion>. Provide label for the header text and put the body content in the default slot.

<mds-accordion>
  <mds-accordion-item label="Cos'e' Magma?">
    <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Come si installa?">
    <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="E' compatibile con React?">
    <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Panel Open by Default

Set selected on the item you want pre-expanded. The parent does not resolve conflicts on load, so in single mode set it on one item only, unless multiple is also set on the parent.

<mds-accordion>
  <mds-accordion-item label="Introduzione" selected>
    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Prerequisiti">
    <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Multiple Panels Open Simultaneously

Add multiple to <mds-accordion> so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.

<mds-accordion multiple>
  <mds-accordion-item label="Configurazione di base">
    <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Configurazione avanzata" selected>
    <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Integrazione CI/CD" selected>
    <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Non-closable Accordion

Set the parent disable-close attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked; with multiple, the last open item cannot be closed. Because disableClose defaults to false, just add the boolean attribute to enable mandatory selection.

<mds-accordion disable-close>
  <mds-accordion-item label="Passo 1 - Installazione" selected>
    <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Passo 2 - Configurazione">
    <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Typography for Section Headers

Use typography to match the panel header to the surrounding document hierarchy. Default is h5; use h3 or h4 for top-level FAQ sections, action for compact control-bar items.

<!-- FAQ section at heading level 3 -->
<mds-accordion>
  <mds-accordion-item label="Come gestisco gli aggiornamenti?" typography="h3">
    <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Posso personalizzare i colori?" typography="h3">
    <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Rich Slot Content

The default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.

<mds-accordion>
  <mds-accordion-item label="Dettagli del progetto">
    <mds-text typography="h6">Tecnologie utilizzate</mds-text>
    <mds-list>
      <mds-list-item>StencilJS</mds-list-item>
      <mds-list-item>TypeScript</mds-list-item>
      <mds-list-item>Storybook</mds-list-item>
    </mds-list>
  </mds-accordion-item>
  <mds-accordion-item label="Contatti del team">
    <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>
  </mds-accordion-item>
</mds-accordion>

Listening to Item Events

mdsAccordionItemChange fires on every toggle; mdsAccordionItemSelect fires only on open; mdsAccordionItemUnselect fires only on close. Use mdsAccordionItemChange when you only need to react to any state change, or the specific event when you need to handle open and close differently. The parent overwrites each item’s id with item-<index> on load, and that is the detail.id: do not select items by an id of your own.

<mds-accordion id="faq">
  <mds-accordion-item label="Domanda frequente 1">
    <mds-text>Risposta alla prima domanda.</mds-text>
  </mds-accordion-item>
  <mds-accordion-item label="Domanda frequente 2">
    <mds-text>Risposta alla seconda domanda.</mds-text>
  </mds-accordion-item>
</mds-accordion>

<script>
  document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {
    console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);
  });

  document.querySelector('#faq mds-accordion-item').addEventListener('mdsAccordionItemSelect', (e) => {
    console.log('faq-1 opened');
  });
</script>

Styling Customization

Style each item only through its documented --mds-accordion-item-* CSS custom properties. Setting vars on the parent <mds-accordion> propagates to all children via the --mds-accordion-* cascade variables the items consume.

/* Customize all items via the parent */
mds-accordion {
  --mds-accordion-border-color: rgb(var(--magma-accent-border));
  --mds-accordion-duration: 200ms;
}

/* Or target a single item directly */
.sidebar mds-accordion-item {
  --mds-accordion-item-color: rgb(var(--magma-text-default));
  --mds-accordion-item-padding-selected: 1.5rem 0 2.5rem 0;
  --mds-accordion-item-padding-unselected: 1rem 0;
}