Avatar Group
Last Updated: September 2026Avatar groups show multiple people in an overlapping cluster, with optional overflow when the list is long.
Source CodeAnatomy
link- 1Avatar
- 2Overlap
- 3Overflow
Variants
linkInitials
Overlapping avatars from unique label initials.
With max
Caps visible avatars and shows a +N overflow badge.
Mixed media
Mix initials and imageUrl; every item still needs a unique label key.
Sizes
linkAvatar groups support 4 sizes: XS, S, M, and L.
Usage Guidelines
linkWhen to use
- •To show multiple people associated with a record, thread, or team.
- •When space is limited and overlapping avatars communicate membership at a glance.
- •With max to collapse long lists into a compact overflow count.
When not to use
- •For a single user — use Avatar or UserProfile.
- •When each person must be fully named and actionable — use a list of UserProfile rows.
- •For non-person entities or status — prefer Icon or Tag.
Give every item a unique label — it keys the list and doubles as initials/alt.
Don't omit or duplicate labels — React keys and overflow math rely on unique label.
Set max when membership can grow so the stack stays scannable.
Don't render unbounded stacks without max in dense UI — layout will blow out.
Behaviors
linkItems
- •items is required — each entry picks Avatar props: label and/or imageUrl.
- •label must be unique; it is used as the React key.
- •size is forwarded to every Avatar and drives overlap spacing.
Overflow
- •max slices the visible list with items.slice(0, max).
- •When max is set and items.length > max, a +N badge shows the remainder.
- •Without max, every item is rendered.
Layout
- •Avatars overlap with negative space-x that scales by size.
- •Each face gets an outline so edges stay visible on shared backgrounds.
Content Guidelines
linkLabels
- •Use 1–2 character initials for label (e.g. SA, JD).
- •Prefer synthetic demo names — never real patient or clinician identifiers.
Images
- •Pass label alongside imageUrl so image alt text is meaningful.
- •Use placeholder or synthetic photos in docs — no real headshots of patients.
Accessibility
linkText & Labels
- •Each Avatar inherits label as image alt when imageUrl is set.
- •Overflow +N is visual only — provide nearby text if membership must be announced.
ARIA attributes
- •AvatarGroup is a layout wrapper (div); it does not expose a listbox role.
- •Individual faces are not interactive unless you wrap them.
Keyboard Support
- •Not focusable by default.
- •If each person is actionable, wrap AvatarGroup children in buttons/links with visible names.
WCAG Compliance Standards
FAQs
linkWhy do items need unique labels?
AvatarGroup keys each child with itemProps.label. Duplicate or missing labels break React reconciliation and remove a reliable initials/alt fallback.
How does max work?
Only the first max items render. If items.length > max, a rounded badge shows +(items.length - max).
AvatarGroup vs UserProfile?
AvatarGroup stacks many faces without names. UserProfile pairs one Avatar with a required name (and optional subtitle).