Avatar·component·@astryxdesign/core

Avatar Group

Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.

Open in Playground @astryxdesign/core/AvatarGroup

Showcases and examples

3 documented examples

Avatar Group

Overlapping avatar rows with a sliced visible set and a server-side overflow count. Shows team members in a compact facepile layout.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · avatar-group-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';

import {AvatarGroup, AvatarGroupOverflow} from '@astryxdesign/core/AvatarGroup';
import {Avatar} from '@astryxdesign/core/Avatar';
import {Stack} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';

const USERS = [
  {
    name: 'Alex Daniels',
    key: 'alex',
  },
  {
    name: 'Ann Smith',
    key: 'ann',
  },
  {
    name: 'Carol Davis',
    key: 'carol',
  },
  {
    name: 'Gina Wilson',
    key: 'gina',
  },
  {
    name: 'Eve Park',
    key: 'eve',
  },
];

export default function AvatarGroupShowcase() {
  return (
    <Stack direction="vertical" gap={8}>
      <Stack direction="vertical" gap={3}>
        <Text type="supporting" color="secondary">
          Team members
        </Text>
        <AvatarGroup size="lg">
          {USERS.map(u => (
            <Avatar key={u.key} name={u.name} />
          ))}
        </AvatarGroup>
      </Stack>
      <Stack direction="vertical" gap={3}>
        <Text type="supporting" color="secondary">
          With overflow
        </Text>
        <AvatarGroup size="lg">
          {USERS.slice(0, 3).map(u => (
            <Avatar key={u.key} name={u.name} />
          ))}
          <AvatarGroupOverflow count={USERS.length - 3} />
        </AvatarGroup>
      </Stack>
    </Stack>
  );
}

Usage

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

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
Don't nest AvatarGroups; use a single group with all avatars.
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.

Typed props

Prop	Type and behavior
`children`	`ReactNode` · required Avatar children, optionally followed by one AvatarGroupOverflow. Consumers handle slicing to the desired visible count. Slot: Avatar
`size`	`AvatarSize` · default 'md' Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.
`shape`	`'circle' \| 'rounded' \| 'square'` · default 'circle' Shape applied to all avatars via context, overriding each avatar's own shape prop. Also applied to AvatarGroupOverflow's "+N" indicator.
`ref`	`React.Ref<HTMLDivElement>` Ref forwarded to the root element.
`xstyle`	`StyleXStyles` StyleX styles for layout customization.
`data-testid`	`string` Test selector for automated testing frameworks.

Anatomy

Avatar children · required

Avatar elements that form the overlapping row. Each can have its own props.

Overflow indicator · optional

A "+N" circle at the end showing hidden count, or a custom AvatarGroupOverflow slot.

Theming

Targets

astryx-avatar-group

Visual props: size, shape

astryx-avatar-group-overflow

Visual props: size, shape