Zetta v1.6

Components · Data display & feedback

Avatar group

A compact stack of overlapping avatars for "who's here" — collaborators on a doc, members of a team. Each avatar wears a canvas-coloured ring so the overlap reads cleanly, and a trailing +N chip collapses the overflow.

Preview

AC LP NR MK +3

Build with the skill

No package to install — hand this to your AI to generate or migrate the component in your stack.

Prompt for your AI 
Apply the Zetta "Avatar group" component to this project using the zetta-design-md skill.

WHEN TO USE
- Migrating or fixing existing code (the common case): audit the current implementation against the `avatar-group` spec (variants: item, overflow) and CORRECT every deviation — replace off-spec values, don't only add new ones.
- New component: build it to the `avatar-group` spec in this project's stack.

AUDIT & FIX (when the component already exists)
Compare it to the skill's spec and fix, don't just append: hardcoded colors/hex, off-scale radius, wrong fonts, dark/navy fills, shadows used in place of borders (or missing borders), brand lime used as a CTA or interaction (must be primary indigo), and any missing or wrong hover / focus / active / disabled / invalid state or missing 2px focus ring. Replace each with the correct Zetta token.

ALWAYS
- Pull the authoritative spec and tokens from the skill — never guess or hardcode values.
- Use this project's own component conventions and framework idioms.
- Honor the Zetta guardrails (brand = identity only, primary = interaction, shadows for overlays) and verify in Light, Dark, and Accessibility.

Anatomy & rules

╭──╮╭──╮╭──╮  +4
│AB││CD││EF│
╰──╯╰──╯╰──╯
  ↑ 8px overlap
State Visual
Default Stacked avatars, overlap by {spacing.xs}
Hover (individual) Hovered avatar rises above stack (z-index +1), tooltip with name
Overflow +N counter chip in {colors.surface-muted} fill after max visible count
Overflow hover Tooltip lists all hidden members

When to use

  • Showing assigned members on a card, issue, or project.
  • Representing a team or a set of collaborators compactly.

When not to use

  • When showing more than 10 total users — show the count only ("42 members") rather than stacking.
  • When each avatar needs individual actions — use a list instead.

Do

  • Set max to 3–5 visible avatars. More than 5 stacked avatars loses legibility.
  • Make the overflow chip interactive — clicking it should open a popover listing remaining users.

Don't

  • Don't stack avatars of mixed sizes.
  • Don't omit the overflow chip when the total count exceeds max.
  • Overflow counter: "+N" format. "+3", "+12". Never "and 3 more".
  • Overflow tooltip: full names of hidden members, comma-separated.
  • Group aria-label: "N members: Name 1, Name 2, and N more".
  • Max visible default: 5. Configurable via maxVisible prop.

Keyboard

Key Behavior
Tab Move focus through visible avatar items
Enter / Space Activate focused avatar (opens profile or triggers action)
Tab Move focus to the overflow chip (if interactive)
Enter / Space Open the overflow popover

Accessibility

  • Group container: role="group" with aria-label describing the context ("Assigned members").
  • Each avatar: aria-label with the user's name.
  • Overflow chip: aria-label="N more members", aria-haspopup="true" if interactive.

Spec

Values and token references resolved straight from the Zetta spec.

avatar-group
display
inline-flex
flexDirection
row-reverse
avatar-group-item
borderColor
{colors.canvas}
borderWidth
2px
borderStyle
solid
borderRadius
{rounded.full}
marginLeft
-8px
avatar-group-item-first
marginLeft
0
avatar-group-overflow
backgroundColor
{colors.surface-muted}
textColor
{colors.muted}
borderColor
{colors.canvas}
borderWidth
2px
borderStyle
solid
borderRadius
{rounded.full}
fontFamily
Geist
fontSize
12px
fontWeight
500
marginLeft
-8px
display
flex
alignItems
center
justifyContent
center
avatar-group-overflow-hover
backgroundColor
{colors.primary-bg}
textColor
{colors.primary}
cursor
pointer
avatar-group-overflow-focus
outline
2px solid {colors.border-focus}
outlineOffset
2px