/// Data Display
AvatarGroup
Overlapping stack of square avatars with a muted +N overflow chip; capped by max.
import { AvatarGroup } from "@protocore/pds";Basics
Pass avatars as items (an array of AvatarProps) or as <Avatar> children. They overlap along the inline axis, each carrying a canvas ring so the stack reads cleanly.
Overflow
max caps how many avatars render; the remainder collapses into a muted +N square that carries an accessible N more label.
Sizes and spacing
size (sm 24 / md 32 / lg 40) sizes every avatar and the overflow chip. spacing tunes the overlap — sm overlaps most, lg least.
When to use it
AvatarGroup condenses a set of people into a single, scannable stack — reviewers on a pull request, members on a project, attendees on an event. It is a display primitive: it shows *who*, not a control for managing membership.
For a single identity with a name and secondary line, use Persona. For a full selectable/linkable row, use ListCell. Give the group an aria-label — it is exposed as one role="group", and the individual avatars' names are decorative within it.
Usage
Do
- Give the group an `aria-label` that names the set (e.g. "Reviewers").
- Keep one `size` across a group so the stack aligns.
- Set `max` to keep long lists compact — the `+N` chip carries the rest.
- Feed data via `items` when the avatars come from an array.
Don't
- Don't mix avatar sizes inside one group.
- Don't use it as a control — it doesn't select or remove members.
- Don't set `max` so high that the stack stops being a summary.
- Don't pass both `items` and `children`; `items` wins.
Accessibility
- The container is a single `role="group"`; label it with `aria-label`.
- The `+N` overflow square is exposed as an image with an `N more` label.
- Each avatar keeps its own image alt / initials — but treat the group label as the primary name.
AvatarGroup props
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label | string | — | Accessible label describing the group (e.g. "Project members"). Recommended — the group is exposed as a single `role="group"` landmark. |
children | ReactNode | — | `<Avatar>` elements, used when `items` is omitted. |
className | string | — | |
items | AvatarProps[] | — | Avatars as data. Each entry is a full set of `AvatarProps` (`src`, `name`, `initials`…). Provide this OR `children`, not both — `items` wins. |
max | number | 5 | Maximum number of avatars to render before collapsing the rest into a `+N` overflow square. |
size | enum | md | Box size applied to every avatar and the overflow square. |
spacing | enum | md | Overlap tightness. |
style | CSSProperties | — |