<!-- Protocore Design System — AvatarGroup -->
# AvatarGroup

- **Category:** Data Display (`data-display`)
- **Slug:** `data-display/avatar-group`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { AvatarGroup } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/data-display/avatar-group

> Overlapping stack of square avatars with a muted +N overflow chip; capped by max.

## 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.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `aria-label` | `string` | no | — | Accessible label describing the group (e.g. "Project members"). Recommended — the group is exposed as a single `role="group"` landmark. |
| `children` | `ReactNode` | no | — | `<Avatar>` elements, used when `items` is omitted. |
| `className` | `string` | no | — | — |
| `items` | `AvatarProps[]` | no | — | Avatars as data. Each entry is a full set of `AvatarProps` (`src`, `name`, `initials`…). Provide this OR `children`, not both — `items` wins. |
| `max` | `number` | no | `5` | Maximum number of avatars to render before collapsing the rest into a `+N` overflow square. |
| `size` | `enum` | no | `md` | Box size applied to every avatar and the overflow square. |
| `spacing` | `enum` | no | `md` | Overlap tightness. |
| `style` | `CSSProperties` | no | — | — |

## Examples

### 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.

```tsx
import { AvatarGroup } from "@protocore/pds";

export default function AvatarGroupBasics() {
  return (
    <AvatarGroup
      aria-label="Project members"
      items={[
        { name: "Ada Lovelace" },
        { name: "Alan Turing" },
        { name: "Grace Hopper" },
        { name: "Katherine Johnson" },
      ]}
    />
  );
}
```

### Overflow

`max` caps how many avatars render; the remainder collapses into a muted `+N` square that carries an accessible `N more` label.

```tsx
import { AvatarGroup } from "@protocore/pds";

export default function AvatarGroupOverflow() {
  const items = [
    "Ada Lovelace",
    "Alan Turing",
    "Grace Hopper",
    "Katherine Johnson",
    "Edsger Dijkstra",
    "Barbara Liskov",
    "Donald Knuth",
  ].map((name) => ({ name }));

  return <AvatarGroup aria-label="Reviewers" max={4} items={items} />;
}
```

## 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

**Notes**

- 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.

## Related

`avatar`, `persona`, `list-cell`, `status-dot`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/