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

Basic Stack with Initials

The most common form: place one item per participant inside mds-avatar-stack. Use initials for users without a photo; the stack applies uniform sizing and overlap automatically.

<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="er"></mds-avatar-stack-item>
</mds-avatar-stack>

Stack with Photos

Use src when a real user photo is available. While src is set, initials is not displayed: an image that cannot be loaded is replaced by the generic person glyph. Items without src show their initials, and the tone/variant placeholder when neither is provided.

<mds-avatar-stack>
  <mds-avatar-stack-item src="/avatars/mario-rossi.jpg" initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item src="/avatars/anna-conti.jpg" initials="ac"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="er"></mds-avatar-stack-item>
</mds-avatar-stack>

Tone and Variant for Placeholder Color

When no image or initials are provided, tone and variant determine the placeholder background. Use distinct variant values to keep users visually distinguishable. tone defaults to weak; use strong for higher contrast.

<mds-avatar-stack>
  <mds-avatar-stack-item variant="blue" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="green" tone="weak"></mds-avatar-stack-item>
  <mds-avatar-stack-item variant="orchid" tone="strong"></mds-avatar-stack-item>
</mds-avatar-stack>

Overflow Counter via Parent total

Set total on the parent to let it append the overflow badge automatically. The badge value is total minus the number of slotted items - do not set count on the items yourself for this use case.

<mds-avatar-stack total="12">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="er"></mds-avatar-stack-item>
</mds-avatar-stack>

Manual Overflow Badge via count

Use count directly on a trailing item only when you are building the overflow indicator yourself and the parent does not own the total. This is rarely needed outside of fully custom stacks.

<mds-avatar-stack>
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
  <mds-avatar-stack-item count="8"></mds-avatar-stack-item>
</mds-avatar-stack>

Size Controlled by the Parent

Size is not set per item - it is set once on the parent with size (sm, md, lg). All items in the stack scale together.

<!-- Small stack: dense lists, table cells -->
<mds-avatar-stack size="sm">
  <mds-avatar-stack-item initials="mr"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="ac"></mds-avatar-stack-item>
</mds-avatar-stack>

<!-- Large stack: profile overviews, hero sections -->
<mds-avatar-stack size="lg">
  <mds-avatar-stack-item initials="er"></mds-avatar-stack-item>
  <mds-avatar-stack-item initials="mt"></mds-avatar-stack-item>
</mds-avatar-stack>

Styling Customization

Style individual items through their documented --mds-avatar-stack-item-* CSS custom properties, or control the whole stack at once via the parent’s --mds-avatar-stack-* counterparts (the item vars inherit from those). Use semantic color roles with rgb(var(--magma-<role>)) so dark mode keeps working.

/* Override the separator ring color for the whole stack */
.collab-panel mds-avatar-stack {
  --mds-avatar-stack-background: rgb(var(--magma-surface-raised));
}

/* Override count badge colors for a specific stack */
.collab-panel mds-avatar-stack {
  --mds-avatar-stack-count-background-color: rgb(var(--magma-accent-emphasis));
  --mds-avatar-stack-count-color: rgb(var(--magma-accent-on-emphasis));
}