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

Basic Auto-Advancing Accordion

The canonical form. Place <mds-accordion-timer-item> children inside the parent, mark exactly one with selected to define the initial panel, and provide a description for each header. The timer starts automatically on load and cycles through items continuously.

<mds-accordion-timer>
  <mds-accordion-timer-item selected description="Introduzione">
    <mds-text>Contenuto del primo pannello.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Caratteristiche">
    <mds-text>Contenuto del secondo pannello.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Conclusioni">
    <mds-text>Contenuto del terzo pannello.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Controlling the Global Cycle Duration

Use the duration prop (in milliseconds) to set how long each item stays open before the accordion auto-advances. The default is 10000 ms (10 seconds). This applies to all items that do not declare their own duration.

<mds-accordion-timer duration="5000">
  <mds-accordion-timer-item selected description="Passo 1">
    <mds-text>Primo contenuto.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Passo 2">
    <mds-text>Secondo contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Per-Item Duration Override

Set duration on individual <mds-accordion-timer-item> children to give each item its own display time. An item-level duration takes precedence over the parent’s global duration for that item only.

<mds-accordion-timer duration="4000">
  <mds-accordion-timer-item selected description="Introduzione rapida" duration="2000">
    <mds-text>Questo pannello rimane aperto per 2 secondi.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Approfondimento" duration="8000">
    <mds-text>Questo pannello rimane aperto per 8 secondi.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Riepilogo">
    <mds-text>Questo pannello usa la durata globale (4 secondi).</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Starting in a Paused State

Set the paused attribute on the parent to start the accordion with the timer frozen. The selected item will display without advancing until paused is removed or the user selects an item. Use this when the auto-advance should not begin until a user action occurs.

<mds-accordion-timer paused>
  <mds-accordion-timer-item selected description="In attesa di avvio">
    <mds-text>Il timer e' in pausa. Rimuovere l'attributo "paused" per avviarlo.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Secondo pannello">
    <mds-text>Secondo contenuto.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

Toggling Pause Programmatically

Toggle the paused prop from JavaScript to freeze and resume the countdown at runtime - for example in response to a user preference or a visibility-change event. Set the prop to undefined or false (or remove the attribute) to resume; in markup never write paused="false".

<mds-accordion-timer id="slideshow">
  <mds-accordion-timer-item selected description="Novita' del mese">
    <mds-text>Contenuto del primo pannello.</mds-text>
  </mds-accordion-timer-item>
  <mds-accordion-timer-item description="Offerte speciali">
    <mds-text>Contenuto del secondo pannello.</mds-text>
  </mds-accordion-timer-item>
</mds-accordion-timer>

<mds-button id="btn-pause" label="Metti in pausa" variant="primary" tone="outline"></mds-button>
<mds-button id="btn-resume" label="Riprendi" variant="primary" tone="strong"></mds-button>

const accordion = document.getElementById('slideshow');
document.getElementById('btn-pause').addEventListener('click', () => {
  accordion.paused = true;
});
document.getElementById('btn-resume').addEventListener('click', () => {
  accordion.paused = undefined;
});

Listening for Item Changes

Listen to the mdsAccordionTimerChange event to react whenever the active item changes - for example to synchronise an external indicator or analytics counter. The event detail carries the zero-based index of the newly selected item.

document.querySelector('mds-accordion-timer').addEventListener('mdsAccordionTimerChange', (e) => {
  console.log('Pannello attivo:', e.detail.index);
});

Programmatic Item Selection

To jump to a specific item from code, set selected = true on that <mds-accordion-timer-item> element directly. The parent intercepts the resulting mdsAccordionTimerItemSelect event, clears paused, and restarts the timer from the beginning of that item.

const items = document.querySelectorAll('mds-accordion-timer-item');
// Apre il terzo pannello e riavvia il timer
items[2].selected = true;

Customizing the Progress Bar via CSS Custom Properties

Style the component only through its documented --mds-accordion-timer-* CSS custom properties. Set them on the parent host or a parent selector; use semantic color roles via rgb(var(--magma-<role>)) so dark mode continues to work.

.promo-slider mds-accordion-timer {
  --mds-accordion-timer-progress-bar-color: rgb(var(--magma-accent-fg));
  --mds-accordion-timer-progress-bar-background: rgb(var(--magma-wash-base));
  --mds-accordion-timer-progress-bar-thickness: 3px;
  --mds-accordion-timer-duration: 300ms;
}