Avatar Group

🧭 When to Use an Avatar Group

Use an Avatar Group when:

• You need to show multiple people or entities together

• You're displaying contributors, viewers, or collaborators in a shared resource

• Visual recognition of participants is helpful, but names aren't required immediately

Avoid using Avatar Groups when the list is long and identity matters — use Avatars with Labels in those cases.

🧩 Component Structure

The group is composed of multiple Avatar components stacked horizontally or visually overlapped using consistent spacing and z-index. Each avatar uses standard Avatar tokens and can include:

• Images

• Initials

• Icons

The group can be capped with a “+X” summary tag if the number of avatars exceeds the visible limit.

🎨 Types

• Default – Avatars display with no additional styling beyond size and image/icon/initials

• Outline – Adds a consistent border (stroke) around each avatar to maintain visibility when overlapped, especially helpful on dark backgrounds or when multiple avatars have similar tones

Toggle these via component variants in Figma.

📏 Sizes

Avatar Group inherits size directly from the Avatar components it contains:

• xsm, sm, md, lg, xl, xxl
  You should use a consistent size across all avatars in a group for visual alignment.

🧠 Behavior

• Overlap – Avatars overlap from left to right (or right to left in RTL) using negative spacing tokens

• Z-index logic – Earlier avatars appear above later ones unless reversed

• Max visible limit – Add a final tag like “+4” to summarize overflow (customizable via text or layer swap)

♿ Accessibility Considerations

From a design perspective:

• Ensure outlines (if used) contrast with all background types

• Limit visible avatars to keep the group readable

• Provide tooltips on hover for individual avatars if clarity is needed

From a code perspective (if implemented):

• Wrap each avatar in a semantic element (<li>, <button>, or <div>)

• Use aria-label or title attributes to describe who each avatar represents

• For the group, use role="group" and consider labeling it (e.g., aria-label="Project team")

✅ Best Practices

• Limit visible avatars to 4–6; use “+X” beyond that

• Use outline type when avatar images lack strong visual contrast

• Maintain consistent avatar size across the group

• Avoid stacking avatars of vastly different shapes or modifiers

• Use tooltips or modals if names or roles must be revealed