AvatarGroup

AvatarGroup displays multiple avatars in an overlapping row with an optional overflow indicator. Uses a compositional API: pass Avatar children directly so each avatar can carry its own props (status dots, click handlers, etc.).

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Avatar Group

AvatarGroup displays multiple avatars in an overlapping row with an optional overflow indicator. Uses a compositional API: pass Avatar children directly so each avatar can carry its own props (status dots, click handlers, etc.).

Usage guidance

• Slice the list yourself and pass only the avatars you want visible; 3-5 is typical. The group renders exactly the children it is given and never slices for you.
• Use AvatarGroupOverflow for custom overflow content like a popover trigger or "add member" button.
• Pass status dots, click handlers, or tooltips directly on each Avatar child.
• Wrap an Avatar child in HoverCard or Tooltip to show more on hover; the avatars still overlap. Set tooltip={false} on the wrapped Avatar so its built-in name tooltip does not compete.
• Make avatars interactive with href or onClick to link to profiles. Interactive avatars share a single Tab stop; arrow keys move between them, and the group announces a keyboard hint to assistive tech. This follows the WAI-ARIA APG roving tabindex technique for managing focus in a composite: https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex
• Avoid: Don't nest AvatarGroups; use a single group with all avatars.
• Avoid: Don't set size on the child avatars. The group's size wins over each child's own size prop, including when the group leaves size at its default, so a child's size is silently ignored inside a group.

Theming API

{
  "targets": [
    {
      "className": "astryx-avatar-group",
      "visualProps": [
        "size",
        "shape"
      ]
    },
    {
      "className": "astryx-avatar-group-overflow",
      "visualProps": [
        "size",
        "shape"
      ]
    }
  ]
}

AvatarGroupOverflow

Anatomy

• Avatar children: Avatar elements that form the overlapping row. Each can have its own props.
• Overflow indicator: A "+N" circle at the end showing hidden count, or a custom AvatarGroupOverflow slot.

Avatar Group Overflow

AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.

Usage guidance

• Pass the real hidden count to count so the accessible label matches the visible indicator.
• Use short custom text such as +12 or 99+. The indicator is circular for short counts and grows into a pill for wider counts so the number always fits.
• Provide onClick when the overflow opens a member list, popover, or detail view.
• Avoid: Do not pass custom text that disagrees with count; count continues to provide the accessible label.
• Avoid: Do not use long labels inside the indicator; place longer participant details next to the group instead.

Default overflow count

<AvatarGroup size="lg">
  {users.slice(0, 3).map(user => (
    <Avatar key={user.id} src={user.src} name={user.name} />
  ))}
  <AvatarGroupOverflow count={users.length - 3} />
</AvatarGroup>

Custom count text

<AvatarGroup size="lg">
  {users.slice(0, 3).map(user => (
    <Avatar key={user.id} src={user.src} name={user.name} />
  ))}
  <AvatarGroupOverflow count={12}>12+</AvatarGroupOverflow>
</AvatarGroup>

Anatomy

• Count label: The compact +N or custom count text displayed inside the circular indicator.
• Button behavior: When onClick is provided, the indicator becomes an interactive button with focus and hover states.

Examples

• Avatar Group Overflow: Overflow indicators for hidden avatars, including the default +N label and custom count text.
• Avatar Group: Overlapping avatar rows with a sliced visible set and a server-side overflow count. Shows team members in a compact facepile layout.
• Avatar — Group: Overlap multiple avatars in a row to represent a group of people. Use for team lists, PR reviewers, or participant counts where you want to show faces without taking up much space.
• Avatar Group — Interactive: A facepile whose avatars link to profiles, with an overflow indicator that opens the full member list. The whole group is one Tab stop; arrow keys move between the avatars and the overflow button.
• Avatar Group Overflow — Custom Text: Provide short custom children such as 12+ when the overflow count needs compact product-specific formatting.
• Avatar Group Overflow — Default Count: Use AvatarGroupOverflow without children to render the standard +N overflow count.