docs / core / avatar-group

AvatarGroup

avatars overlapped into one cluster, so a crowd reads at a glance. the caption carries the claim, the faces carry the proof.

intensity · recedesrsc · server

provenance

shaped from sisu-plus

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

hero social proof, participant lists, shared ownership rowsthe tinted cluster pairs tone on the group with tone on each Avatarnever more faces than max can justify. five visible is the ceilingnot a picker. the stack does not click

a11y

each Avatar keeps its own alt · the +N chip and caption are plain textjest-axe
live demo · try it out
ALBPMCED+2
+128 students
customize
maxvisible faces before +N
4
sizeoverlap and +N chip size
tonecolours the +N chip and faces
labelthe caption after the stack
usagecopy
import { Avatar, AvatarGroup } from "@usva-ui/react/primitives/avatar";

<AvatarGroup max={4} label="+128 students">
  <Avatar alt="Ada" fallback="AL" />
  <Avatar alt="Blaise" fallback="BP" />
  <Avatar alt="Curie" fallback="MC" />
</AvatarGroup>

props

proptypedefaultnotes
maxnumber—caps the visible avatars. the rest collapse into a +N chip.
size"sm" | "md" | "lg""md"overlap spacing and +N chip size. match the Avatars inside.
labelReactNode—caption after the stack, e.g. "25+ active users".
tone"solid" | "accent" | "neutral""neutral"colors the +N chip. pair it with the Avatar tone.

get it

bun add @usva-ui/reactcopy
usagecopy
import { Avatar, AvatarGroup } from "@usva-ui/react/primitives/avatar";

<AvatarGroup max={4} label="+128 students">
  <Avatar alt="Ada" fallback="AL" />
  <Avatar alt="Blaise" fallback="BP" />
  <Avatar alt="Curie" fallback="MC" />
  <Avatar alt="Dijkstra" fallback="ED" />
  <Avatar alt="Euler" fallback="LE" />
</AvatarGroup>