Skip to main content

AvatarGroup

Show a compact stack of avatars with an overflow count.

SCJD+2
Props
Slots

Anatomy#

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.

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 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.

<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.

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.

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
data-status
Slot: avatar-group-itemavatar-imageavatar-fallback
Description: Stores async loading, loaded, or error status.

Props#

Props for the AvatarGroup component. Renders a <div> element by default.

Prop