Correct and idiomatic ways to use the <mds-push-notification-item> 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 Message Notification

The minimal form: a message body with an icon and a relative timestamp. Always nest the item inside mds-push-notification, which manages stacking and animation.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/email"
    subject="Nuovo messaggio"
    message="Hai ricevuto 3 nuovi messaggi da account diversi"
    datetime="2024-06-01T10:30:00"
  ></mds-push-notification-item>
</mds-push-notification>

Variant for Semantic Status

Use variant to communicate meaning - success, warning, error, info - and tone to set visual weight. The values are forwarded to the internal <mds-avatar>.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/check-circle"
    subject="Salvataggio completato"
    message="Il documento e' stato salvato con successo"
    datetime="2024-06-01T10:31:00"
    variant="success"
    tone="strong"
  ></mds-push-notification-item>

  <mds-push-notification-item
    icon="mi/baseline/warning"
    subject="Attenzione"
    message="La sessione scadra' tra 5 minuti"
    datetime="2024-06-01T10:32:00"
    variant="warning"
    tone="weak"
  ></mds-push-notification-item>
</mds-push-notification>

Dismissable Notification

Add the deletable attribute to show the dismiss button, letting the user close the notification manually. Without it the notification cannot be dismissed by the user - keep it off for system notifications the user must not close.

<mds-push-notification>
  <mds-push-notification-item
    deletable
    icon="mi/baseline/email"
    subject="Nuovo messaggio"
    message="Hai ricevuto un nuovo messaggio"
    datetime="2024-06-01T09:00:00"
    variant="info"
  ></mds-push-notification-item>
</mds-push-notification>

Action Buttons via the action Slot

Slot one or more <mds-button> elements into slot="action" for in-notification CTAs. Use size="sm" to keep the actions compact.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/person"
    subject="Mario Giannini"
    message="Ciao, sono Mario, questo e' il mio contatto, buona giornata!"
    datetime="2024-06-01T10:25:00"
    variant="primary"
    tone="strong"
  >
    <mds-button slot="action" variant="success" tone="weak" size="sm" label="Accetta"></mds-button>
    <mds-button slot="action" variant="error" tone="weak" size="sm" label="Ignora"></mds-button>
  </mds-push-notification-item>
</mds-push-notification>

Badge Label via the badge Slot

Slot an <mds-badge> into slot="badge" to show a category or type label above the subject line.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/attach-file"
    subject="Nuovo allegato"
    message="Hai ricevuto un nuovo file allegato da Luca Bianchi"
    datetime="2024-06-01T10:20:00"
    variant="primary"
  >
    <mds-badge slot="badge" variant="amaranth" tone="weak" label="pdf"></mds-badge>
    <mds-button slot="action" tone="outline" size="sm" label="Scarica"></mds-button>
  </mds-push-notification-item>
</mds-push-notification>

Avatar Mode with Image

Set src and preview="avatar" to display a user photo as a round avatar instead of the default full-width image preview.

<mds-push-notification>
  <mds-push-notification-item
    src="./avatar-sarah.jpeg"
    preview="avatar"
    subject="Sarah Ho"
    message="Ciao, sono Sarah, questo e' il mio contatto, buona giornata!"
    datetime="2024-06-01T10:15:00"
    variant="primary"
    tone="strong"
  >
    <mds-button slot="action" variant="success" tone="weak" size="sm" label="Scrivi"></mds-button>
  </mds-push-notification-item>
</mds-push-notification>

Avatar Mode with Initials Fallback

When no image is available, set initials and preview="avatar". The initials override tone and variant coloring so the user stays visually distinguishable.

<mds-push-notification>
  <mds-push-notification-item
    initials="MG"
    preview="avatar"
    subject="Mario Giannini"
    message="Ha modificato il documento condiviso"
    datetime="2024-06-01T10:10:00"
  ></mds-push-notification-item>
</mds-push-notification>

Inline Image Preview

Omit preview="avatar" (or keep the default image) and supply src to show the image as a larger inline thumbnail - useful for file or media notifications.

<mds-push-notification>
  <mds-push-notification-item
    src="./book-cover-01.webp"
    subject="Anteprima immagine"
    message="La copertina e' stata aggiornata"
    datetime="2024-06-01T10:05:00"
  ></mds-push-notification-item>
</mds-push-notification>

Fixed Date Format

Use any dayjs-compatible format string as date-format to show a static date instead of the default relative “time ago” display.

<mds-push-notification>
  <mds-push-notification-item
    icon="mi/baseline/event"
    subject="Promemoria riunione"
    message="La riunione di progetto e' fissata per domani"
    datetime="2024-06-01T09:00:00"
    date-format="DD/MM/YYYY"
  ></mds-push-notification-item>
</mds-push-notification>

Listening to the Dismiss Event

Listen to mdsPushNotificationItemClose to handle cleanup when the user dismisses the item. The parent <mds-push-notification> does this automatically, but you can also add your own logic (e.g. marking the notification read in the server). The event carries no detail: identify the notification from the element itself, here its id.

document
  .querySelector('mds-push-notification-item')
  .addEventListener('mdsPushNotificationItemClose', (event) => {
    const { id } = event.target;
    markNotificationRead(id);
  });

Styling Customization

Customize the item only through its documented --mds-push-notification-item-* CSS custom properties.

.app-notifications mds-push-notification-item {
  --mds-push-notification-item-shadow: var(--shadow-md-sharp);
  --mds-push-notification-item-message-line-clamp: 3;
  --mds-push-notification-item-subject-line-clamp: 2;
  --mds-push-notification-item-icon-background-color: rgb(var(--magma-accent-emphasis));
  --mds-push-notification-item-icon-color: rgb(var(--magma-accent-on-emphasis));
}