AvatarGroup

Stack of avatars representing a collection of users, with optional overflow tile and shared sizing.

stable
since v0.1.0
1.93 kB
feedback
identity
user

Preview

tsx

import { Avatar, AvatarGroup } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <AvatarGroup>
      <Avatar name="Jane Doe" />
      <Avatar name="John Smith" />
      <Avatar name="Ada Lovelace" />
    </AvatarGroup>
  );
}

With overflow

Use max to cap how many avatars render inline. Excess avatars collapse into a +N overflow tile that is automatically labelled for assistive tech.

Preview

Open

tsx

import { Avatar, AvatarGroup } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <AvatarGroup max={3}>
      <Avatar name="Jane Doe" />
      <Avatar name="John Smith" />
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" />
      <Avatar name="Linus Torvalds" />
      <Avatar name="Margaret Hamilton" />
    </AvatarGroup>
  );
}

Sizes

The group’s size cascades to every child avatar (children may still override individually).

Preview

Open

tsx

import { Avatar, AvatarGroup } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
      <AvatarGroup size="sm">
        <Avatar name="Jane Doe" />
        <Avatar name="John Smith" />
        <Avatar name="Ada Lovelace" />
      </AvatarGroup>
      <AvatarGroup size="md">
        <Avatar name="Jane Doe" />
        <Avatar name="John Smith" />
        <Avatar name="Ada Lovelace" />
      </AvatarGroup>
      <AvatarGroup size="lg">
        <Avatar name="Jane Doe" />
        <Avatar name="John Smith" />
        <Avatar name="Ada Lovelace" />
      </AvatarGroup>
    </div>
  );
}

Ring and shape

ring is on by default to separate stacked avatars; pass ring={false} to disable. Use shape to switch between circle (default), rounded, and square tiles.

Preview

Open

tsx

import { Avatar, AvatarGroup } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
      <AvatarGroup shape="circle" max={4}>
        <Avatar name="Jane Doe" />
        <Avatar name="John Smith" />
        <Avatar name="Ada Lovelace" />
        <Avatar name="Grace Hopper" />
        <Avatar name="Linus Torvalds" />
      </AvatarGroup>
      <AvatarGroup shape="rounded" max={4}>
        <Avatar name="Jane Doe" shape="rounded" />
        <Avatar name="John Smith" shape="rounded" />
        <Avatar name="Ada Lovelace" shape="rounded" />
        <Avatar name="Grace Hopper" shape="rounded" />
        <Avatar name="Linus Torvalds" shape="rounded" />
      </AvatarGroup>
      <AvatarGroup ring={false} max={4}>
        <Avatar name="Jane Doe" />
        <Avatar name="John Smith" />
        <Avatar name="Ada Lovelace" />
        <Avatar name="Grace Hopper" />
        <Avatar name="Linus Torvalds" />
      </AvatarGroup>
    </div>
  );
}

Custom overflow

renderOverflow lets you swap the default +N tile for a fully custom node — useful for buttons that open a member list.

Preview

Open

tsx

import { Avatar, AvatarGroup } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <AvatarGroup
      max={2}
      renderOverflow={(count) => (
        <button
          type="button"
          aria-label={`Show ${count} more collaborators`}
          style={{
            all: 'unset',
            cursor: 'pointer',
            display: 'inline-flex',
            alignItems: 'center',
            justifyContent: 'center',
            width: '2.5rem',
            height: '2.5rem',
            borderRadius: '9999px',
            background: 'var(--cy-color-neutral-3, #eef0f4)',
            color: 'var(--cy-color-neutral-12, #1a1f2c)',
            fontSize: '0.8125rem',
            fontWeight: 600,
          }}
        >
          +{count}
        </button>
      )}
    >
      <Avatar name="Jane Doe" />
      <Avatar name="John Smith" />
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" />
      <Avatar name="Linus Torvalds" />
    </AvatarGroup>
  );
}

API

PropTypeDefaultDescription

size

"xs"|"sm"|"md"|"lg"|"xl"|"2xl"

Size applied to every child avatar via context. One of `xs`, `sm`, `md`, `lg`, `xl`, `2xl`.

shape

"circle"|"square"|"rounded"

circle

Shape applied to the overflow tile and used as the visual default. One of `circle`, `square`, `rounded`.

ring

boolean

true

Render a halo ring on each child avatar so overlap reads cleanly.

max

number

—

Maximum number of child avatars to render inline. Excess avatars collapse into a `+N` overflow tile.

renderOverflow

((count: number) => ReactNode)

—

Render override for the overflow tile. Receives the hidden count.

Accessibility

Each child Avatar should carry a name so screen readers can announce membership individually.
The overflow tile sets aria-label="{N} more" so assistive tech reports the hidden count.
Avoid stacking more than a handful of avatars without a max — long stacks become noisy to navigate.
When the group represents a list, wrap it in a labelled landmark (<section aria-label="Collaborators">).

Recipes

Use max={3} or max={5} to keep dense rosters compact.
Pair each avatar with a Tooltip so full names are accessible on hover and focus.
Pass renderOverflow={(n) => <button>+{n}</button>} to make the overflow tile open a member dialog.
Set ring={false} on backgrounds where the default ring colour blends in.