AvatarGroup

Displays a stacked group of Avatars with shared size and overlap.

Examples

Basic

KJ

<AvatarGroup {...args}>
  <Avatar name="Ada Lovelace" src="https://i.pravatar.cc/256?img=47" />
  <Avatar name="Grace Hopper" src="https://i.pravatar.cc/256?img=32" />
  <Avatar name="Katherine Johnson" />
</AvatarGroup>

With Overflow

KJ

+4

<AvatarGroup {...args}>
  <Avatar name="Ada Lovelace" src="https://i.pravatar.cc/256?img=47" />
  <Avatar name="Grace Hopper" src="https://i.pravatar.cc/256?img=32" />
  <Avatar name="Katherine Johnson" />
  <AvatarGroupOverflow count={4} />
</AvatarGroup>

Clickable Overflow

AL

GH

+8

<AvatarGroup {...args}>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" />
  <AvatarGroupOverflow count={8} onClick={() => undefined} />
</AvatarGroup>

Sizes

AL

GH

KJ

+4

AL

GH

KJ

+4

AL

GH

KJ

+4

AL

GH

KJ

+4

AL

GH

KJ

+4

<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
  {(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(size => (
    <AvatarGroup aria-label={`${size} group`} key={size} size={size}>
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" />
      <Avatar name="Katherine Johnson" />
      <AvatarGroupOverflow count={4} />
    </AvatarGroup>
  ))}
</div>

Numeric Sizes

AL

GH

+5

AL

GH

+5

AL

GH

+5

<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
  {([24, 48, 96] as const).map(size => (
    <AvatarGroup aria-label={`${size}px group`} key={size} size={size}>
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" />
      <AvatarGroupOverflow count={5} />
    </AvatarGroup>
  ))}
</div>

Custom Overflow Content

AL

GH

View all

<AvatarGroup {...args}>
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" />
  <AvatarGroupOverflow count={12}>View all</AvatarGroupOverflow>
</AvatarGroup>

Forwarded Props

AL

GH

+4

<AvatarGroup
  {...args}
  data-analytics="member-group"
  id="member-group"
  onMouseEnter={() => undefined}
  title="Project members">
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" />
  <AvatarGroupOverflow
    count={4}
    data-analytics="member-overflow"
    onClick={() => undefined}
    title="View all members"
  />
</AvatarGroup>

API

AvatarGroup

Displays a stacked group of Avatars with shared size and overlap.

Prop	Type	Default	Description
aria-label	string	—	Accessible label for the group. Default is "Avatars".
children*	ReactNode	—	Avatar and AvatarGroupOverflow children.
className	string	—	Additional CSS class names applied to the root element.
data-testid	string	—	Test ID applied to the root element.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
size	"small" | "tiny" | "xsmall" | "medium" | "large" | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180	—	Size applied to child Avatars. Individual Avatar size props are ignored while inside the group so the stack remains visually consistent.
style	CSSProperties	—	Inline styles applied to the root element.

AvatarGroupOverflow

Overflow indicator showing the count of hidden avatars in an AvatarGroup.

Prop	Type	Default	Description
children	ReactNode	—	Custom content rendered instead of the default "+N" text.
className	string	—	Additional CSS class names applied to the root element.
count*	number	—	Number of hidden avatars represented by the overflow indicator.
data-testid	string	—	Test ID applied to the root element.
onClick	MouseEventHandler<HTMLButtonElement>	—	Click handler. When set, the overflow indicator renders as a button.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.
style	CSSProperties	—	Inline styles applied to the root element.