MiHCM
data/@mihcm/ui·v0.21.0·stable

AvatarGroup

Stacked, overlapping row of Avatar components with an overflow "+N" count. The size prop forwards to children. max controls the visible limit.

ConfiguratorExamplesUsageAccessibilityApi

AvatarGroup

Stacked, overlapping row of Avatar components with an overflow "+N" count badge. Shows at most max avatars, then a counter for the rest.

When to use

  • Assignee lists — show who is assigned to a task or ticket.
  • Participant indicators — meeting attendees, collaborators.
  • Compact user lists — anywhere space is tight and a full list is overkill.

When NOT to use

  • When each avatar needs its own action (click to view profile) — use a list instead.
  • For a single user — use Avatar directly.

Import

import { AvatarGroup } from '@mihcm/ui/AvatarGroup';
import { Avatar, AvatarFallback, AvatarImage } from '@mihcm/ui/Avatar';

Basic usage

<AvatarGroup max={3}>
  <Avatar>
    <AvatarImage src="/people/photos/jane-doe.jpg" alt="Jane Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/people/photos/alex-kim.jpg" alt="Alex Kim" />
    <AvatarFallback>AK</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/people/photos/maya-chen.jpg" alt="Maya Chen" />
    <AvatarFallback>MC</AvatarFallback>
  </Avatar>
</AvatarGroup>

Size forwarding

Pass size to AvatarGroup and it forwards to all children via cloneElement.

<AvatarGroup max={3} size="sm">
  <Avatar>
    <AvatarImage src="/people/photos/jane-doe.jpg" alt="Jane Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/people/photos/alex-kim.jpg" alt="Alex Kim" />
    <AvatarFallback>AK</AvatarFallback>
  </Avatar>
</AvatarGroup>

Composition

  • Pass max to limit visible avatars. Overflow renders as a "+N" badge.
  • size on the group forwards to all children — no need to set it on each Avatar.
  • overlap="none" | "sm" | "md" | "lg" controls stack density.
  • direction="row-reverse" mirrors the visual order for right-aligned surfaces.
  • stackOrder="first-on-top" keeps the first avatar visually above later avatars.
  • renderOverflow lets you replace the "+N" badge with a custom tokenized summary.
  • Pair with a Tooltip on the overflow badge to list remaining names.