# AvatarGroup

> A few people at a glance, overlapping, with a count for the rest.

- **Level**: molecule · **Status**: stable · **Role**: content
- **Import**: `import { AvatarGroup } from "@rrios-forge/ui/molecules/avatar-group";`
- **Source**: `packages/ui/src/molecules/avatar-group`

Overlapping cluster of avatars with a `+N` overflow chip. The first `max` entries render overlapped and ringed; the remainder collapse into a decorative `+N` chip (aria-hidden). The container is role=group — pass `label` to name it. Size mirrors the Avatar atom scale. Patterns consulted: Patterns/Information Architecture · MetadataAndActions, Patterns/Density & Growth · MetadataCompression.

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` `lg` `xl` | `md` | Ergonomic scale, in three families (control, text, container). |
| `lead` | — | `true` `false` | `false` | AvatarGroup leading avatar emphasis. |

## Stories

- [Playground](/?path=/story/components-molecules-avatargroup--playground) · frame: `/iframe.html?id=components-molecules-avatargroup--playground&viewMode=story`
- [Sizes](/?path=/story/components-molecules-avatargroup--sizes) · frame: `/iframe.html?id=components-molecules-avatargroup--sizes&viewMode=story`
- [Overflow chip](/?path=/story/components-molecules-avatargroup--overflow) · frame: `/iframe.html?id=components-molecules-avatargroup--overflow&viewMode=story`
- [No overflow](/?path=/story/components-molecules-avatargroup--no-overflow) · frame: `/iframe.html?id=components-molecules-avatargroup--no-overflow&viewMode=story`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).