AvatarGroup

AvatarGroup

<AvatarGroup max={3} total={12} size="sm">
  <Avatar fallback="AL" />
  <Avatar fallback="BO" />
  <Avatar fallback="CA" />
  <Avatar fallback="DE" />
</AvatarGroup>

Install: @helixui/core

import { AvatarGroup } from '@helixui/core'

status: stable · since: 0.2.0

Tags: users, collaborators, stacked, overflow

Anatomy

( ●●●●  +12 )  ← overlapping avatars + overflow chip

Layout

• display — inline-flex
• width — content
• height — content
• intrinsicSize — hugs N avatars with negative inline gap
• stackable — true
• fullBleed — false

Visual

A row of avatars with negative left margin so each avatar overlaps the previous by ~30%. Each has a thin border that matches the surface so the overlap reads as separation. A +N overflow chip is the last child when there are more than max avatars.

Props

Name	Type	Default	Description
max	number	—	Cap visible avatars; rest go into the +N chip.
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	md	Avatar size; applied to all children.
total	number	—	Override total count when children is only the visible subset.

Slots

• children — Avatar elements

Tokens used

color.bg.surface.default, color.bg.action.neutral.default, color.text.secondary, radius.full, font.family.sans, font.weight.semibold, font.size.xs, font.size.sm, font.size.md, font.size.xl

Accessibility

Notes

• The overflow chip has aria-label="N more".
• Pass meaningful alt to each Avatar for screen-reader output.

Composes with

Component	Relation	Note
Avatar	child	Each child is an Avatar.
List	child	Often rendered as the trailing slot of a list row.

Prompt examples

These are the AI prompt → JSX mappings used by the helixui prompt DSL and integrations like Cursor / Claude Code.

show a small collaborator pile

“show the first 4 avatars and +N chip for the rest”

<AvatarGroup max={4}>
  {users.map(u => <Avatar key={u.id} fallback={u.initials} src={u.image} />)}
</AvatarGroup>

Related

• Avatar