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

# AvatarGroup

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

## Anatomy

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

## Usage

Use AvatarGroup to show a small set of people in a bounded space. It truncates the visible stack at
`maxVisible`. Keep the full membership available elsewhere when users need every name. For a single person,
use [Avatar](https://moraine.subf.dev/components/avatar.md).

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

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

### Overflow count

Each entry in `items` accepts the [Avatar](https://moraine.subf.dev/components/avatar.md) props. The group
`size` (default `md`) overrides an entry's `size`. AvatarGroup renders nothing for an empty `items`
array, and items keep input order in the DOM.

Omit `maxVisible` to show every avatar. A positive `maxVisible` is rounded down. Set `maxVisible` to `0` (or any negative
value) to show only the `+N` count. `N` is the number of hidden items.

```tsx
<AvatarGroup maxVisible={3} items={reviewers} />
<AvatarGroup maxVisible={0} items={reviewers} />
```

## Examples

### Show pull request reviewers

Cap the stack with `maxVisible` so a long reviewer list stays in one row. The overflow count is the rest of
the membership.

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

export function GroupingUsage() {
  return (
    <AvatarGroup
      maxVisible={3}
      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',
        },
        {
          src: 'https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=128&fit=crop&q=80',
          alt: 'Michael Scott',
          text: 'MS',
        },
        {
          src: 'https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=128&fit=crop&q=80',
          alt: 'Jane Wilson',
          text: 'JW',
        },
      ]}
    />
  )
}
```

### Collapse reviewers to a count

A positive `maxVisible` shows that many faces plus `+N`. Set `maxVisible={0}` to render only the remainder count
when the row has no room for faces.

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

const REVIEWERS = [
  {
    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',
  },
  {
    alt: 'Elena Rostova',
    text: 'ER',
    icon: 'i-lucide:user',
  },
  {
    src: 'https://images.unsplash.com/photo-1500648767791-00dcc994a43e?w=128&fit=crop&q=80',
    alt: 'Michael Scott',
    text: 'MS',
  },
  {
    src: 'https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=128&fit=crop&q=80',
    alt: 'Jane Wilson',
    text: 'JW',
  },
] satisfies AvatarGroupT.Item[]

export function OverflowCount() {
  return (
    <div class="space-y-4">
      <div class="space-y-1.5">
        <p class="text-xs text-muted-foreground">Faces plus remainder</p>
        <AvatarGroup maxVisible={3} items={REVIEWERS} />
      </div>
      <div class="space-y-1.5">
        <p class="text-xs text-muted-foreground">Count only</p>
        <AvatarGroup maxVisible={0} items={REVIEWERS} />
      </div>
    </div>
  )
}
```

## API Reference

### 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>  /** URL of the avatar image. Surrounding whitespace is trimmed. When empty or missing the status is<br>`error` and the fallback is shown; changing it restarts loading. */<br>  src?: string;<br>  /** Alt text of the image and accessible name of the fallback. When `text` is not set, the fallback<br>shows up to two initials taken from the first letters of the first words of `alt`. */<br>  alt?: string;<br>  /** Name of an icon rendered in a small badge anchored to a corner of the avatar (see<br>`badgePosition`). Nothing is rendered when omitted. */<br>  badge?: IconT.Name;<br>  /** Text shown in the fallback while the image is loading, failed, or missing, typically initials.<br>It is trimmed, and when blank the initials of `alt` are used instead. Ignored when `icon` is set. */<br>  text?: string;<br>  /** Name of an icon shown in the fallback in place of `text` or initials while the image is unavailable. */<br>  icon?: IconT.Name;<br>  /** Called whenever the image status changes, including once after mount with the initial status<br>(`loading` when `src` is set, otherwise `error`). The status is `loaded` once the image has<br>loaded and `error` when it fails or `src` is empty. It is not called on the server. */<br>  onStatusChange?: (status: Status) => void;<br>} & {<br>  /** Visual size of the component. */<br>  size?: 'sm' \| 'md' \| 'lg';<br>  /** Position of the badge relative to the avatar. */<br>  badgePosition?: 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right';<br>})[] \| undefined | [] | Avatars to render, in order. Each entry accepts the `Avatar` props (`src`, `alt`, `text`,<br>`icon`, `badge`, `badgePosition`, `onStatusChange`). An entry's `size` is<br>overridden by the group `size`. An empty array renders nothing. |
| maxVisible | number \| undefined | — | Maximum number of avatars shown. The remaining ones are replaced by a single `+N` count<br>element. Fractions are rounded down and negative values show none. All items are shown when<br>`undefined`. |
| 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. |

**`items` example**

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

<AvatarGroup
  items={[
    { src: '/alex.png', alt: 'Alex Rivera' },
    { text: 'BK', alt: 'Blake Kim', badge: 'icon-success' },
  ]}
/>
```
