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

Minimal Auto-Managed Stack

The default behavior="auto" configuration. Drop mds-push-notification-item children into the default slot and the container shows itself, animates each item in, and hides itself when all items have been dismissed. Set deletable on an item to give it its own close button.

<mds-push-notification>
  <mds-push-notification-item
    deletable
    subject="Nuovo messaggio"
    message="Il documento e' pronto per la revisione."
  ></mds-push-notification-item>
</mds-push-notification>

Items with Avatar Preview

Use preview="avatar" and src to show a user photo. Supply initials as a fallback when no image is available.

<mds-push-notification>
  <mds-push-notification-item
    preview="avatar"
    src="/avatars/marco.jpg"
    initials="MC"
    subject="Marco Cicognetti"
    message="Ci sei andato poi alla riunione?"
  ></mds-push-notification-item>
</mds-push-notification>

Items with Icon Preview

Use icon (an icon slug with its set prefix) instead of src when the notification represents an event or system action rather than a person.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/attachment"
    subject="Documento allegato"
    message="E' stato caricato un nuovo allegato nella pratica 2024-1042."
  ></mds-push-notification-item>
</mds-push-notification>

Item with Date and Timestamp

Pass an ISO 8601 datetime string to display a relative time-ago label (default) or a static formatted date.

<mds-push-notification>
  <mds-push-notification-item
    subject="Approvazione completata"
    message="La richiesta e' stata approvata."
    datetime="2024-11-12T09:30:00Z"
  ></mds-push-notification-item>

  <!-- Static date format -->
  <mds-push-notification-item
    subject="Scadenza contratto"
    message="Il contratto scade il giorno indicato."
    datetime="2024-12-31T00:00:00Z"
    date-format="DD/MM/YYYY"
  ></mds-push-notification-item>
</mds-push-notification>

Item with Action Button

Slot an mds-button into the action slot of the item to provide an inline CTA.

<mds-push-notification>
  <mds-push-notification-item
    preview="avatar"
    src="/avatars/sara.jpg"
    subject="Sara Ho"
    message="Hai ricevuto una nuova richiesta di collaborazione."
  >
    <mds-button slot="action" variant="primary" tone="weak" size="sm">
      Rispondi
    </mds-button>
  </mds-push-notification-item>
</mds-push-notification>

Manual Behavior with Programmatic Control

Set behavior="manual" when visibility should be controlled by your application logic rather than inferred from slot contents. Toggle the visible attribute or call show() / hide() on the element.

<mds-push-notification behavior="manual" id="notif-panel">
  <mds-push-notification-item
    subject="Aggiornamento sistema"
    message="Un aggiornamento e' disponibile. Riavviare per applicarlo."
  ></mds-push-notification-item>
</mds-push-notification>

<script>
  const panel = document.querySelector('#notif-panel');

  // Show programmatically
  panel.show();

  // Hide programmatically
  panel.hide();
</script>

Programmatic Dismissal of a Single Item

Call removeNotification() with an mds-push-notification-item element reference to animate it out and remove it without the user interacting with the close button.

<mds-push-notification id="notif-panel">
  <mds-push-notification-item id="item-1"
    subject="Avviso temporaneo"
    message="Questa notifica viene rimossa dopo 5 secondi."
  ></mds-push-notification-item>
</mds-push-notification>

<script>
  const panel = document.querySelector('#notif-panel');
  const item = document.querySelector('#item-1');

  setTimeout(() => {
    panel.removeNotification(item);
  }, 5000);
</script>

Reacting to Visibility Events

Listen to mdsPushNotificationShow, mdsPushNotificationHide, or mdsPushNotificationChange to synchronize UI state when the panel opens or closes.

const panel = document.querySelector('mds-push-notification');

panel.addEventListener('mdsPushNotificationShow', () => {
  console.info('Pannello notifiche aperto');
});

panel.addEventListener('mdsPushNotificationHide', () => {
  console.info('Pannello notifiche chiuso');
});

panel.addEventListener('mdsPushNotificationChange', (e) => {
  console.info('Visibilita cambiata:', e.detail.visible);
});

Item Tone and Variant

Use variant and tone on the item to reflect the semantic nature of the notification (status or theme family). tone accepts strong or weak on this component. They paint the item’s icon or avatar preview, so they show only together with icon (or preview="avatar").

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/check-circle"
    variant="success"
    tone="weak"
    subject="Operazione completata"
    message="Il file e' stato salvato con successo."
  ></mds-push-notification-item>

  <mds-push-notification-item
    icon="mi/baseline/error"
    variant="error"
    tone="strong"
    subject="Errore critico"
    message="Impossibile completare l'operazione. Riprovare."
  ></mds-push-notification-item>
</mds-push-notification>

Styling Customization via CSS Custom Properties

Override animation timing, inter-item gap, and the panel background through the documented --mds-push-notification-* properties. Set them on the host or a parent selector; for colours name a semantic role, rgb(var(--magma-<role>)) (agents/color.md).

mds-push-notification {
  --mds-push-notification-items-intro-delay: 200ms;
  --mds-push-notification-items-outro-delay: 100ms;
  --mds-push-notification-items-duration: 250ms;
  --mds-push-notification-items-gap: calc(var(--spacing) * 300);
  --mds-push-notification-fadeout-delay: 0.5s;
  --mds-push-notification-background: linear-gradient(
    to right,
    rgb(var(--magma-surface-overlay) / 0) 0%,
    rgb(var(--magma-surface-overlay) / 0.95) 100%
  );
}