Avatar

Last updated: October 14, 2026

User avatar with image fallback, sizes, an overlapping AvatarGroup with +N overflow, and an optional status dot.

Installation

npx smoothui-cli add avatar

Image with initials or custom fallback while loading or on error
Sizes sm (24px), md (32px), lg (40px)
AvatarGroup stacks avatars and collapses extras into a +N chip via max
Optional status dot (online, away, busy, offline) with an accessible label
Compound parts: AvatarRoot, AvatarImage, AvatarFallback, AvatarStatus, AvatarGroup, AvatarGroupOverflow
Base UI by default; Radix twin available via style

Three sizes. Pass src and fallback; the fallback shows until the image loads.

AvatarGroup with max={3} shows three avatars and a +2 overflow chip. The group size is inherited by children.

Presence dots sit on the bottom-right edge and scale with the avatar size.

Attribute	Element	Purpose
`alt`	Image	Describes the person; use `alt=""` for decorative images
`role="group"` + `aria-label`	AvatarGroup	Names the stack, e.g. "Project members"
`role="img"` + `aria-label`	Status / Overflow	Announces the presence state or "N more"

base-ui

SmoothUI

Animated React components with smooth Motion animations. Drop-in shadcn/ui compatible.