---
title: AvatarGroup
description: Show a compact stack of avatars with an overflow count.
package: moraine
version: 0.6.0
repository: https://github.com/subframe7536/moraine
---

# AvatarGroup

> Show a compact stack of avatars with an overflow count.

Use AvatarGroup to show a small set of people in a bounded space. It truncates the visible stack at `max`; keep the full membership available elsewhere when users need it.

## Basic usage

```tsx
import { AvatarGroup } from 'moraine'

export function Example() {
  return <AvatarGroup items={[{ src: '/alex.png', alt: 'Alex', fallback: 'A' }]} />
}
```

## Anatomy

```text
AvatarGroup [component; slot=root]
├── item [slot]
│   ├── image [slot]
│   ├── fallback [slot]
│   │   └── fallbackContent [slot]
│   └── badge [slot]
└── count [slot]
```

## Usage

### Grouping avatars

AvatarGroup renders no root for an empty `items` array. Avatar items retain input order in the DOM. `max` is a number: omit it to show every avatar, set it to `0` to show only `+N`, or use a positive number to show its floored count. The overflow count follows the visible items.

```tsx
import { AvatarGroup } from 'moraine'

export function GroupingUsage() {
  return (
    <AvatarGroup
      items={[
        {
          src: 'https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=128&fit=crop&q=80',
          alt: 'Sarah Connor',
          text: 'SC',
        },
        {
          src: 'https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=128&fit=crop&q=80',
          alt: 'Marcus Vance',
          text: 'MV',
        },
        {
          src: 'https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=128&fit=crop&q=80',
          alt: 'Elena Rostova',
          text: 'ER',
        },
      ]}
    />
  )
}
```

## Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-status` | `avatar-group-item`, `avatar-image`, `avatar-fallback` | Stores async loading, loaded, or error status. |

## Props

Props for the AvatarGroup component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items | ({<br>  /** Source URL for the avatar image. */<br>  src?: string;<br>  /** Accessible alt text for the avatar. */<br>  alt?: string;<br>  /** Icon name for the badge. */<br>  badge?: IconT.Name;<br>  /** Position of the badge. */<br>  badgePosition?: NonNullable<Variant['badgePosition']>;<br>  /** Initial text to show if image fails or is missing. */<br>  text?: string;<br>  /** Icon name to show as fallback. */<br>  fallback?: IconT.Name;<br>  /** Callback when the loading status of the avatar changes. */<br>  onStatusChange?: (status: Status) => void;<br>})[] \| undefined | [] | Array of avatars to render in the group. |
| max | number \| undefined | — | Maximum number of avatars to show. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |