# AvatarGroup

> Overlapping avatars for a compact "who's involved" cluster, with an optional +N overflow chip.

URL: https://apogee.avaui.dev/docs/avatar-group
Last updated: 2026-10-15

Overlapping avatars for a compact "who's involved" cluster, with an optional +N overflow chip.

Last updated October 15, 2026

```astro
<AvatarGroup
items={[
  { name: 'Jordan Lee', src: 'https://i.pravatar.cc/80?img=12' },
  { name: 'Priya Nair' },
  { name: 'Sam Ito', src: 'https://i.pravatar.cc/80?img=5' },
  { name: 'Casey Wren' },
]}
max={3}
/>
```

## Add

```sh
npx @ava-ui/apogee add avatar-group
```

Pulls in `Avatar`.

## Usage

```astro
---
import AvatarGroup from '@/components/apogee/AvatarGroup/AvatarGroup.astro'
---
<AvatarGroup items={[{ name: 'Jordan Lee' }, { name: 'Priya Nair' }]} max={5} />
```

## Anatomy

-   **`items` mode** — pass an `items` array; AvatarGroup renders an `Avatar` per entry (each gets the group’s `size`) plus a **+N overflow chip** when `items.length > max`.
-   **Manual mode** — omit `items` and drop `<Avatar>` children into the default slot instead; you control each avatar’s props (including its own `size`). The overlap (`-space-x-2`) and ring (`ring-2 ring-page`) styling apply either way.

## API

`@composable` — exposed to Content Editors in AVA. Any other native `<div>` attribute passes through.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `{ src?: string; name?: string; alt?: string }[]` | — | Renders one `Avatar` per entry. Omit to use the default slot instead. |
| `max` | `number` | — | Show at most this many `items`, then a `+N` chip. Omit to show all. Ignored in manual (slot) mode. |
| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` | Size applied to each generated `Avatar` and to the overflow chip. Doesn’t affect manually slotted avatars — set their own `size`. |
| `class` | `string` | — | Extra classes, merged last. |

## Sizes

```astro
<AvatarGroup size="xsmall" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="small" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="large" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
<AvatarGroup size="xlarge" items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }]} />
```

## States

With overflow (`items.length > max`) vs. without (`max` omitted or ≥ `items.length`):

```astro
<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }, { name: 'E F' }, { name: 'G H' }]} max={2} />
<AvatarGroup items={[{ name: 'A B' }, { name: 'C D' }]} />
```

## Examples

Manual composition — mixed sizes or custom per-avatar props aren’t possible via `items`:

```astro
<AvatarGroup>
<Avatar name="Jordan Lee" src="https://i.pravatar.cc/80?img=12" />
<Avatar name="Priya Nair" />
</AvatarGroup>
```

## Accessibility

-   Each `Avatar` carries its own accessible name (image `alt` or the initials fallback’s `aria-label`) — see [Avatar](https://apogee.avaui.dev/avatar).
-   The `+N` overflow chip is plain visible text (e.g. “+3”), not a control — it’s not focusable and doesn’t disclose the hidden names. If the overflow count needs to be actionable (e.g. open a full list), wrap the group in a `<button>` yourself; AvatarGroup doesn’t do this.

## Tokens

| Token | Used for |
| --- | --- |
| `--background-page` | Ring color separating overlapping avatars (`ring-2 ring-page`) |
| `--background-neutral` | Overflow chip background |
| `--foreground-neutral` | Overflow chip text |

## Do / Don’t

-   **Do** set `max` for groups that could grow unbounded (team members, watchers).
-   **Do** keep `size` consistent within a group.
-   **Don’t** mix `items` and slotted children — `items` (when set) takes over the default slot entirely.
-   **Don’t** expect the `+N` chip to be interactive — it’s static text.

## Content

-   No component-specific copy — the overflow chip’s “+N” is generated, not authored.

## Related

[

AvatarA user image, with an initials fallback derived from name.

](https://apogee.avaui.dev/docs/avatar)[

BadgeA small status label — for counts, tags, and state indicators.

](https://apogee.avaui.dev/docs/badge)