---
title: AvatarGroup
description: Group of overlapping avatars with an optional overflow count.
sidebar:
  order: 5
search:
  tags: [profiles, stack, overflow, users]
---

# AvatarGroup

> Group of overlapping avatars with an optional overflow count.

## Import

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

## Usage

`AvatarGroup` renders multiple `Avatar` items as an overlapping group with an optional overflow count.
Use [`Avatar`](https://ui.subf.dev/avatar.md) for a standalone avatar.

## Slot Structure

```text
root
├── count (optional, overflow count)
└── item (×n)
    ├── image
    ├── fallback
    │   └── fallbackIcon (Icon, optional)
    └── badge (optional)
```

## Examples

### Basic

```tsx
function Basic() {
  return <AvatarGroup items={[{ text: 'A' }, { text: 'B' }, { text: 'C' }]} />
}
```

### Overflow Count

```tsx
function Overflow() {
  return (
    <AvatarGroup
      max={3}
      items={[
        { text: 'AL' },
        { text: 'BM' },
        { text: 'CN', badge: 'i-lucide-check', badgePosition: 'top-right' },
        { text: 'DO' },
        { text: 'EP' },
      ]}
    />
  )
}
```

### Sizes

```tsx
function Sizes() {
  const SIZES: AvatarGroupSize[] = ['xs', 'sm', 'md', 'lg', 'xl']

  return (
    <div class="flex flex-wrap gap-4 items-end">
      <For each={SIZES}>
        {(size) => (
          <div class="flex flex-col gap-2 items-center">
            <AvatarGroup
              size={size}
              max={2}
              items={[{ text: 'A' }, { text: 'B' }, { text: 'C' }]}
            />
            <span class="text-xs text-muted-foreground font-mono">{size}</span>
          </div>
        )}
      </For>
    </div>
  )
}
```

## API Reference

### Attributes

#### `root`

Container of grouped avatars.

#### `item`

Individual avatar wrapper used when rendering grouped avatars.

#### `count`

Count indicator shown when a group has more avatars than the visible limit.

#### `image`

Loaded avatar image rendered inside each frame.

#### `fallback`

Text fallback shown while an image is unavailable or failed.

#### `fallbackIcon`

Icon fallback shown when no image or text fallback is available.

#### `badge`

Status or indicator badge anchored to an avatar frame.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| class | ClassValue | — | Class applied to the component root or trigger element. |
| classes | AvatarGroupT.Classes \| undefined | — | — |
| items | AvatarGroupT.Item[] \| undefined | [] | Array of avatars to render in the group. |
| max | string \| number \| undefined | — | Maximum number of avatars to show. |
| ref | JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined | — | — |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined | — | — |
| style | JSX.CSSProperties \| undefined | — | — |
| styles | AvatarGroupT.Styles \| undefined | — | — |
| transition | "none" \| "fast" \| "normal" \| "slow" \| undefined | — | — |

### Items

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| alt | string \| undefined | — | Accessible alt text for the avatar. |
| badge | IconT.Name | — | Icon name for the badge. |
| badgePosition | NonNullable<"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| undefined> \| undefined | bottom-right | Position of the badge. |
| fallback | IconT.Name | — | Icon name to show as fallback. |
| onStatusChange | ((status: AvatarStatus) => void) \| undefined | — | Callback when the loading status of the avatar changes. |
| src | string \| undefined | — | Source URL for the avatar image. |
| text | string \| undefined | — | Initial text to show if image fails or is missing. |

### ARIA

Accessibility attributes and roles emitted by the component markup.

| Attribute | Type | Description |
| --- | --- | --- |
| aria-hidden | boolean \| string \| undefined | Hides decorative content from assistive technology. |

### Data Attributes

State and slot attributes exposed for styling hooks and selectors.

| Attribute | Type | Description |
| --- | --- | --- |
| data-slot | string | Identifies the rendered slot for styling hooks and selectors. |
| data-status | string \| undefined | Stores async loading, loaded, or error status. |