Skip to content
rdloom

Avatar Group

An overlapping stack of avatars with a +N chip for the rest, for showing who is on a team, thread or file.

Displayv0.1.0experimentalWCAG 2.2 AAView spec
import { AvatarGroup } from "@rdloom/react";

export default function AvatarGroupBasicExample() {
  return (
    <AvatarGroup
      label="Team members"
      avatars={[{ name: "Ada Lovelace" }, { name: "Grace Hopper" }, { name: "Katherine Johnson" }]}
    />
  );
}

Installation

npx rdloom add avatar-group

Copies the source into src/components/rdloom. Edit it freely: rdloom upgrade merges later versions into your changes.

Use another registry client
npx shadcn@latest add https://rdloom.vimalbhatt.com/r/avatar-group.json

Works, but without upgrade tracking.

Usage

import { AvatarGroup } from "@rdloom/react";

<AvatarGroup
  label="Team members"
  avatars={[{ name: "Ada Lovelace" }, { name: "Grace Hopper" }, { name: "Katherine Johnson" }]}
/>

With overflow

import { AvatarGroup } from "@rdloom/react";

export default function AvatarGroupWithOverflowExample() {
  return (
    <AvatarGroup
      label="Team members"
      max={3}
      avatars={[
        { name: "Ada Lovelace" },
        { name: "Grace Hopper" },
        { name: "Katherine Johnson" },
        { name: "Margaret Hamilton" },
        { name: "Hedy Lamarr" },
      ]}
    />
  );
}

Sizes

import { AvatarGroup } from "@rdloom/react";

const people = [{ name: "Ada Lovelace" }, { name: "Grace Hopper" }, { name: "Katherine Johnson" }, { name: "Hedy Lamarr" }];

export default function AvatarGroupSizesExample() {
  return (
    <div className="flex flex-col items-start gap-3">
      <AvatarGroup label="Reviewers" size="xs" max={3} avatars={people} />
      <AvatarGroup label="Reviewers" size="sm" max={3} avatars={people} />
      <AvatarGroup label="Reviewers" size="md" max={3} avatars={people} />
      <AvatarGroup label="Reviewers" size="lg" max={3} avatars={people} />
    </div>
  );
}

API Reference

Defined by the spec. Components also accept the props of the React Aria component they wrap.

PropTypeDefault
avatarsrequired

The people, each with a name and an optional image URL.

Array<{ name: string; src?: string }>none
max

How many avatars to show before the +N chip.

number4
size

Avatar size, as for Avatar.

"xs" | "sm" | "md" | "lg""md"
label

What the group is, e.g. "Team members". It starts the accessible name, followed by the names.

string"Members"

Accessibility

Role img, WCAG 2.2 AA. Tested with axe and keyboard tests; screen reader checks are in the audit checklist.

Keyboard

Not interactive.

Screen readers announce

  • Announced once as an image with the full list and the count of the rest

What your code must do

  • The group is an image with one accessible name listing the people, e.g. "Team members: Ada Lovelace, Grace Hopper and 3 more"
  • Individual avatars inside it are hidden from assistive technology so nothing is read twice
  • The +N chip is part of the same name, not separate text
  • Initials and the chip text meet 4.5:1 against their background

Guidelines

Use it when

  • Showing the people on a project, thread or document
  • A compact list where full names appear elsewhere

Avoid it when

  • Each person needs to be reached or opened: use a list of links
  • One person: use Avatar

Don't

  • An empty label
  • Using it as the only place the people are named when it matters who they are

Design tokens

The semantic tokens this component uses. Change them once and every component follows; see Design tokens.

  • --rd-color-surface-subtle
  • --rd-color-surface-default
  • --rd-color-text-default
  • --rd-color-border-default