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

Basic Text Toast

The simplest form. Set visible to show the toast; the default slot holds the message text only. The component auto-dismisses after the default 5000 ms.

<mds-toast visible>
  Operazione completata con successo
</mds-toast>

Status Variants

Use variant to communicate the meaning of the feedback. The status family (error, warning, info, success) maps directly to the nature of the event. Do not pick a variant for its color alone.

<!-- Conferma positiva -->
<mds-toast visible variant="success">
  Documento salvato correttamente
</mds-toast>

<!-- Errore bloccante -->
<mds-toast visible variant="error">
  Errore durante il salvataggio. Riprova.
</mds-toast>

<!-- Avviso non bloccante -->
<mds-toast visible variant="warning">
  La sessione scade tra 5 minuti
</mds-toast>

<!-- Informazione neutrale -->
<mds-toast visible variant="info">
  Aggiornamento disponibile
</mds-toast>

Tone for Emphasis

Pair variant with tone to adjust visual weight. strong (default) uses the stronger tint of the variant and a larger shadow; weak uses a softer tint and a smaller shadow for lower emphasis.

<!-- Forte enfasi: errore urgente -->
<mds-toast visible variant="error" tone="strong">
  Connessione persa
</mds-toast>

<!-- Enfasi ridotta: info secondaria -->
<mds-toast visible variant="info" tone="weak">
  Sincronizzazione in background
</mds-toast>

Toast with Icon

Use the icon slot with an <mds-icon> to add a leading glyph. The icon color inherits from --mds-toast-icon-color which is tuned per variant.

<mds-toast visible variant="success">
  <mds-icon slot="icon" name="mi/baseline/check-circle"></mds-icon>
  File caricato con successo
</mds-toast>

Toast with Action

Use the action slot with an <mds-button> to offer a follow-up. The action region appears only while a [slot="action"] child is present, also when it is added after the first render - no empty layout is produced otherwise.

<mds-toast visible variant="error">
  <mds-icon slot="icon" name="mi/baseline/error-outline"></mds-icon>
  Invio non riuscito
  <mds-button slot="action" size="sm" variant="error" tone="weak">
    Riprova
  </mds-button>
</mds-toast>

Persistent Toast (No Auto-Dismiss)

Set duration="0" to keep the toast visible until the user explicitly acts. Use this when the message carries an action the user must not miss. The toast has no close control of its own: hide it from your action handler by removing visible.

<mds-toast visible variant="warning" duration="0">
  <mds-icon slot="icon" name="mi/baseline/warning"></mds-icon>
  Sessione in scadenza
  <mds-button slot="action" size="sm" variant="warning" tone="weak">
    Rinnova
  </mds-button>
</mds-toast>

Custom Auto-Dismiss Duration

Override the 5000 ms default when the message needs more reading time (e.g. it carries an action) or can disappear faster (e.g. a trivial confirmation). Duration is in milliseconds.

<!-- Messaggio breve: 2 secondi -->
<mds-toast visible variant="success" duration="2000">
  Copiato negli appunti
</mds-toast>

<!-- Con azione: 8 secondi -->
<mds-toast visible variant="info" duration="8000">
  Importazione completata con 3 avvisi
  <mds-button slot="action" size="sm" variant="info" tone="weak">
    Vedi report
  </mds-button>
</mds-toast>

Positioning

Use position to anchor the toast to one of the six viewport edges. Pick the edge that matches the application’s layout convention - bottom-center is the default and works for most surfaces.

<!-- Predefinito: centro in basso -->
<mds-toast visible variant="info" position="bottom-center">
  Messaggio salvato
</mds-toast>

<!-- Angolo in alto a destra (toolbar / panel) -->
<mds-toast visible variant="success" position="top-right">
  Impostazioni aggiornate
</mds-toast>

Listening for the Close Event

Listen for mdsToastClose to remove the toast from the DOM or update queue state after the outro animation completes. It is emitted only when the duration timer dismisses the toast. Do not react to visible becoming false directly - the animation is still running at that point.

document.querySelector('mds-toast').addEventListener('mdsToastClose', () => {
  // rimuovi il toast dalla coda o aggiorna lo stato dell'applicazione
  toastQueue.shift();
});

Styling Customization

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

.app-notifications mds-toast {
  --mds-toast-background: rgb(var(--magma-surface-inverse));
  --mds-toast-color: rgb(var(--magma-on-inverse));
  --mds-toast-icon-color: rgb(var(--magma-on-inverse));
  --mds-toast-width: 480px;
  --mds-toast-shadow: var(--shadow-xl);
}