Correct and idiomatic ways to use the <mds-avatar> 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.

Profile Image via src

The most common form: supply a URL and the component loads the image lazily. If the image fails to load the component falls back to the generic person glyph automatically - no extra wiring needed.

<mds-avatar src="https://example.com/foto-utente.jpg"></mds-avatar>

Initials Fallback

When no photo is available, provide the user’s initials. The component displays the first two characters, uppercased, so pass the initials rather than the full name. It also derives a deterministic color from the characters (ignoring non-alphanumeric ones) so the same person always maps to the same hue.

<mds-avatar initials="MR"></mds-avatar>
<!-- displayed as "MR" with a stable identity color -->

<mds-avatar initials="ab"></mds-avatar>
<!-- displayed as "AB" -->

Manual Variant and Tone (no initials)

When initials is not set, you can control the avatar background and icon color through variant and tone. Use this for non-personal entity avatars where identity color is not required.

<!-- Primary brand color, filled -->
<mds-avatar variant="primary" tone="strong" icon="mi/baseline/support-agent"></mds-avatar>

<!-- Success semantic, weak tint -->
<mds-avatar variant="success" tone="weak"></mds-avatar>

Icon Avatar for Non-Personal Entities

Use icon when the avatar represents a system, service, or non-human entity. Reference icons by their slug (no .svg extension). The generic person fallback is replaced by the provided icon.

<mds-avatar icon="mi/baseline/business" variant="primary"></mds-avatar>
<mds-avatar icon="mi/baseline/pets" variant="info"></mds-avatar>

Overflow Count in Stacked Groups

Use count to render a “+N” overflow badge for the last slot in an avatar stack (e.g. “3 more”). The count display overrides initials and icon (with src set as well the avatar renders empty) and, unlike initials, derives no color: it keeps the variant. Use inside mds-avatar-stack and mds-avatar-stack-item.

<mds-avatar-stack>
  <mds-avatar-stack-item src="https://example.com/foto-01.jpg"></mds-avatar-stack-item>
  <mds-avatar-stack-item src="https://example.com/foto-02.jpg"></mds-avatar-stack-item>
  <mds-avatar-stack-item count="3"></mds-avatar-stack-item>
</mds-avatar-stack>

Sizing via Utility Classes

<mds-avatar> does not expose a size prop - its size is controlled by the host element’s width (the component uses aspect-ratio: 1/1 internally). Apply a Magma spacing utility class on the host.

<!-- Small avatar -->
<mds-avatar src="https://example.com/foto.jpg" class="w-600"></mds-avatar>

<!-- Default / medium avatar -->
<mds-avatar src="https://example.com/foto.jpg" class="w-1200"></mds-avatar>

<!-- Large avatar -->
<mds-avatar src="https://example.com/foto.jpg" class="w-2400"></mds-avatar>

Styling Customization

Style the avatar only through its documented --mds-avatar-* CSS custom properties. Use semantic color roles wrapped in rgb(var(--magma-<role>)) so dark mode and high-contrast modes work correctly.

.profilo-utente mds-avatar {
  --mds-avatar-background-color: rgb(var(--magma-accent-emphasis));
  --mds-avatar-color: rgb(var(--magma-accent-on-emphasis));
  --mds-avatar-radius: var(--magma-radius-md);
  --mds-avatar-initials-padding: 15%;
}

Square Avatar via --mds-avatar-radius

The default shape is fully circular. Override the CSS custom property to get a square or rounded-square avatar - for example when representing a product or brand logo rather than a person.

.logo-azienda mds-avatar {
  --mds-avatar-radius: var(--magma-radius-md);
}

<mds-avatar
  class="logo-azienda w-1600"
  src="https://example.com/logo-azienda.png"
></mds-avatar>