AddThisFeature

Avatar Group

Show who is involved in a compact space without a pile of broken images.

moderate Components & Primitives

What it adds

A stacked set of member avatars with deterministic ordering, an overflow count, and access to the full list.

What your agent is told to do

5
  1. 1

    Find the places that show several people at once — assignees, collaborators, workspace members, comment participants — and render them through one grouped component.

  2. 2

    Order the stack deterministically by a stable rule such as role then name, so the same group renders in the same order on every load and every device.

  3. 3

    Cap the number shown and collapse the remainder into a single count that is announced meaningfully, not as a bare number sitting after a row of pictures.

  4. 4

    Make the group activatable to reveal the full list of people with their full names, since the stack itself can only ever be a summary.

  5. 5

    Do not rely on a photograph being present. Every member needs a fallback built from their name, and every fallback needs to survive a missing name, a single-character name, and a name in a non-Latin script.

Edge cases it handles

7
  • Unstable ordering makes the same group look like different groups across two pages. Sort by a stable field rather than by whatever order the API returned.
  • The overflow indicator must be a real count with an accessible name explaining what it counts, and activating it must reach the same full list as the group itself.
  • Two members with the same initials produce two identical circles. Vary the fallback deterministically per person and make sure hovering or activating still resolves who is who.
  • The full membership must be reachable without hovering, since hover is unavailable on touch and unreliable with a keyboard.
  • Avatar images fail to load often enough that the failure is the normal case. The fallback must render immediately and must not leave a broken image icon or an empty hole in the stack.
  • A group with one member should not render as a stack, and a group with none needs a defined empty treatment rather than a lone overflow bubble.
  • Overlapping avatars must not overlap their hit areas if each is individually interactive; either give each a clear target or make only the group activatable.

Definition of done

8
  • The same set of people renders in the same order on every load.
  • Overflow collapses into a count with an accessible description.
  • The full member list is reachable by keyboard and on touch.
  • Missing images fall back to a generated placeholder with no broken image state.
  • Members with identical initials are visually and textually distinguishable.
  • Groups of zero and of one have defined treatments distinct from the stacked case.
  • The feature matches the existing design system.
  • No existing functionality is broken.

Related features

How it works

  1. 1

    Copy the link

    Grab the Markdown instruction URL for this feature.

  2. 2

    Give it to your AI

    Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.

  3. 3

    It inspects, then implements

    Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.