Initials
When no src is provided, Avatar generates initials from the name prop (up to 2 characters). Each name maps deterministically to one of 8 background/foreground color pairs so the same user always gets the same color.
Fallback icon
When neither src nor name is available, a generic person icon is shown.
Sizes
xs
sm
md
lg
xl
xs24pxInline mentions, dense comment threads.sm32pxList rows, table cells, compact headers.md40pxDefault. Profile cards, comment threads.lg48pxProfile pages, prominent user callouts.xl64pxAccount settings page, hero user display.Square shape
Set shape="square" for bots, apps, or integrations where a circular shape implies a human user.
Status indicator
Add a status prop to show a presence dot in the bottom-right corner. The dot has a white ring border so it remains legible on any background.
AvatarGroup
Stacks avatars with a 25% overlap and a white outline ring. When the list exceeds max, a +N overflow count appears at the end.
4 visible, +2 overflow
AKBOCDDC+2sm size
AKBOCDDC+2In context — comment thread
Looks great — just a couple of alignment notes on the token table.
Left some comments in the Figma. Ready to review when you are.
Approved. Nice work on the dark mode tokens.
Keyboard & accessibility
role="img"Avatar is marked as an image landmark.aria-labelSet to the name prop (or "User avatar" as fallback). Screen readers announce this as the accessible name.Status dotaria-label set to the status string ("online", "away", etc.) so screen readers can discover presence state.img alt textWhen src is provided, the <img> gets alt={name} (or "Avatar" fallback).AvatarGroup +NOverflow count has aria-label="{N} more" to announce the hidden count.Usage guidance
DoAlways pass name when it's available — initials are more informative than the fallback icon.DoUse square shape for non-human entities (bots, apps, integrations).DoUse AvatarGroup for collaborator lists — max 4–5 visible before overflow.Don'tUse avatars as navigation targets. Wrap in a link or button instead.Don'tShow status indicators when presence data isn't real-time — stale status is misleading.Don'tUse xl size in dense lists — it overwhelms row content. Reserve for profile pages.Tokens used
bg/mutedFallback background (no name, no src)bg/baseAvatarGroup outline ring and status dot bordertext/subtleFallback icon colorborder-width/baseSubtle border on initials avatars (transparent by default)status/successOnline status dotstatus/warningAway status dotstatus/errorBusy status dotborder/baseOffline status dotradius/sm–xlSquare shape radius scales with sizefont/baseInitials and overflow count typeface