Avatar

Usage

Variants

Sizes

Shadow

Opt-in elevation for hero/profile contexts — adds a layered outer drop shadow plus a glassy inner highlight rim. Default avatars stay flat so they read cleanly inline and in groups; reserve shadow for places like the profile-page hero and the MindIsland-style surfaces.

Group

Overlapping avatars for "people on this thing." AvatarGroup handles the negative-space stacking and adds a ring around each child so the overlap reads cleanly on any surface.

API Reference

Avatar

AvatarImage

Forwards every native <img> attribute. Renders null while loading or on error so the fallback shows.

AvatarFallback

Renders when the image is unavailable. Use 1–2 letter initials, an icon, or a Lucide-style glyph.

AvatarGroup

A flex row that overlaps its Avatar children via negative space and adds ring-surface-primary to each so the overlap reads on any surface. Inherits size from its children — pass size="sm" or size="lg" on each Avatar to scale the whole group.

AvatarGroupCount

A squircle "+N" tile that sits at the end of an AvatarGroup. Same shape, size, and ring treatment as the avatars next to it. Use for overflow ("+12 more").

Guidelines

• Always include AvatarFallback — the image can be missing, slow, or broken, and a blank circle reads as a bug.
• Set alt on AvatarImage describing the person, not "Avatar of Alice" — screen readers say "image" already.
• Use initials in AvatarFallback; one letter is fine when first/last names aren't both known.
• Use Avatar for logos or non-human entities; reach for a plain <img> or a custom badge.
• Stack avatars manually with negative margins. Use AvatarGroup so the overlap and stacking stay consistent.