---
name: avatar-group
category: media
summary: "Overlapping avatar stack with +N overflow"
subpath: "@42/core/avatar-group"
---

Overlapping stack of avatars with optional `+N` overflow collapsing. Headless: the
controller reflects `data-stacked` / `data-spacing` and caps visible avatars; the
overlap visuals live in CSS.

```html
<div data-c42-avatar-group>
  <div data-c42-avatar>…</div>
  <div data-c42-avatar>…</div>
  <div data-c42-avatar>…</div>
  <span data-c42-avatar-overflow></span>
</div>
```

```ts
import { AvatarGroup } from '@42/core/avatar-group';
const group = new AvatarGroup(root, { stacked: true, spacing: 'md', max: 4, label: 'Members' });
group.setMax(2);
```

Options: `stacked` (default true), `spacing` ('sm'|'md'|'lg', default 'md'), `max` (0 = no limit), `label` (aria-label)
Methods: `setStacked(boolean)`, `setSpacing('sm'|'md'|'lg')`, `setMax(number)`, `refresh()`
Events: `avatar-group:change` → `{ total, visible, overflow }`