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

Badge Inside mds-button via Named Slot

The most common usage. Drop <mds-notification> into the notification slot of mds-button so the badge is positioned and animated automatically by the button’s internal layout. Set strategy="disabled" because the button handles placement (without a target the component also switches to it by itself); the component is no longer responsible for floating positioning.

<mds-button label="Messaggi" icon="mdi/email" variant="primary" tone="weak">
  <mds-notification slot="notification" value="5" strategy="disabled"></mds-notification>
</mds-button>

Floating Badge Anchored to an Arbitrary Element

Use the target prop with a CSS selector to attach a floating badge to any element on the page. The component uses position: fixed by default and tracks the target through scroll and resize automatically.

<mds-notification target="#icona-notifiche" value="12"></mds-notification>
<mds-icon id="icona-notifiche" name="mi/baseline/notifications"></mds-icon>

Count Overflow via max

When raw counts can grow large, set max to cap the visible number. Values above the cap display as +max (e.g. +99), keeping the badge compact.

<mds-notification target="#posta-in-arrivo" value="127" max="99"></mds-notification>
<mds-icon id="posta-in-arrivo" name="mi/baseline/mail"></mds-icon>

Hiding and Showing the Badge

Add the dismissed prop to hide the badge independently of its count. This is useful when the notification state is known but should not be displayed yet - for example while a panel is already open.

<!-- Badge nascosto anche se ha un valore -->
<mds-notification target="#avatar-utente" value="3" dismissed></mds-notification>

<!-- Badge visibile (valore predefinito) -->
<mds-notification target="#avatar-utente" value="3"></mds-notification>

Zero Value Produces an Empty Dot

When value is 0 the badge renders without a number, appearing as a plain dot. Use this when you need an unread marker without a count - for example to signal new activity without exposing a specific number.

<mds-notification target="#attivita-recente" value="0"></mds-notification>
<mds-button id="attivita-recente" label="Attivita" variant="primary" tone="weak"></mds-button>

Absolute Positioning Strategy

Use strategy="absolute" when the badge must be positioned relative to a scrolling container rather than the viewport. The target element must have position: relative (or another non-static position) set on its nearest containing block.

<div style="position: relative; overflow: auto;">
  <mds-notification target="#elemento-lista" value="2" strategy="absolute"></mds-notification>
  <mds-button id="elemento-lista" label="Documenti" variant="primary"></mds-button>
</div>

Disabled Strategy for Manual Placement

Use strategy="disabled" when you want to position the badge yourself with utility classes or CSS instead of delegating to the floating-UI engine. This is the right choice whenever the badge lives inside a slot (the slot’s host already controls layout) or when you use Tailwind position utilities.

<mds-button label="Avvisi" icon="mi/baseline/notifications" variant="primary" tone="strong">
  <mds-notification
    slot="notification"
    value="4"
    strategy="disabled"
  ></mds-notification>
</mds-button>

Styling Customization via CSS Custom Properties

Customize the badge only through the documented --mds-notification-* CSS custom properties. Set them on the host element or a parent selector. Use the Magma color tokens with rgb(var(--<token>)) so dark mode and high-contrast stay consistent.

/* Colore di sfondo personalizzato, cerchio senza bordo */
.header-nav mds-notification {
  --mds-notification-dot-background: rgb(var(--magma-warning-emphasis));
  --mds-notification-color: rgb(var(--magma-warning-on-emphasis));
  --mds-notification-ring-size: 0px;
  --mds-notification-size: 18px;
}