Avatar-group

Overlapping stack of avatars showing a collection of people: project members, comment participants, assignees. CSS-only.

When to use

• Showing 2-6 people associated with a thing.
• Compact visual of a team or audience.

For longer lists, show the first few + overflow indicator (+N), then link to a full list view.

Variants

Anatomy

<div class="avatar-group">
  <span class="avatar">A</span>
  <span class="avatar">B</span>
  <span class="avatar">C</span>
  <span class="avatar -overflow">+5</span>
</div>

<!-- With images -->
<div class="avatar-group -tight">
  <img class="avatar" src="alex.jpg" alt="Alex" />
  <img class="avatar" src="bo.jpg" alt="Bo" />
  <img class="avatar" src="chris.jpg" alt="Chris" />
</div>

The component uses CSS to:

• Negative margin each avatar onto the previous one
• Add a border in the surface color so each avatar reads as separate
• Stack first avatar on top via z-index

Tokens used

• --size-control-m — base avatar size for overlap math
• --color-surface-canvas — border (default)
• --color-surface-raised — border (on-raised variant) + overflow bg
• --color-ink-regular — overflow text
• --border-width-emphasis — border thickness

Component-tier (defined inline)

• --avatar-group-overlap — overridable overlap amount

Accessibility

The group itself is decorative — there is no list semantics. If the group represents a meaningful collection (e.g. assignees to a task), wrap it in a labeled container:

<div aria-label="Assigned to 8 people">
  <div class="avatar-group">
    <span class="avatar" aria-label="Alex">A</span>
    <span class="avatar" aria-label="Bo">B</span>
    <span class="avatar -overflow" aria-label="and 6 more">+6</span>
  </div>
</div>

The individual avatar accessibility is the consumer's choice — for an image avatar, <img alt=""> is correct; for an initials avatar, an aria-label carries the name.

Edge cases

• Long names: the overflow avatar uses the same size as the others, so labels longer than +99 may need a .-overflow.-tight override.
• On any background: if the surrounding surface is not surface-canvas, override the border via .-on-raised or a custom declaration; otherwise avatars merge into the background.
• Single avatar: the group still works with one avatar; the overlap rule is a no-op without a sibling.

Do

• Limit visible avatars to 4-6 + an overflow indicator.
• Order most-important first (they sit on top).
• Match the border color to the surface the group sits on.

Don't

• Don't put a list of 20 avatars in a group. Use a different display.
• Don't mix avatar sizes within one group — overlap math assumes uniform size.