7onicDESIGN SYSTEM

Avatar

Avatar is a component that visually represents a user or entity. Supports image, initials, and icon fallbacks, with status indicators and group display.

2
Shapes
6
Sizes
4
Status
Radix
Base

Playground

Preview
D
JD
Size
Shape
Content
Options
Status
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Sizes

xs
Size24px
Font10px
Dot6px
sm
Size32px
Font12px
Dot8px
default
Size40px
Font14px
Dot10px
lg
Size48px
Font16px
Dot12px
xl
Size64px
Font20px
Dot14px
2xl
Size80px
Font24px
Dot16px

Features

Shapes

JD
Circle
JD
Square
<Avatar shape="circle">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar shape="square">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Status

JD
online
JD
offline
JD
busy
JD
away
<Avatar status="online">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>
<Avatar status="offline">...</Avatar>
<Avatar status="busy">...</Avatar>
<Avatar status="away">...</Avatar>

Fallback

When an image fails to load, initials or an icon are shown as a fallback.

JD
Image + Fallback
JD
Initials
Icon
{/* Image with fallback */}
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

{/* Initials only */}
<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

{/* Icon fallback */}
<Avatar>
  <AvatarFallback>
    <User className="w-1/2 h-1/2" />
  </AvatarFallback>
</Avatar>

Avatar Group

Displays multiple avatars stacked together. Use max to limit the number shown.

JDEBMKRS
<AvatarGroup>
  <Avatar>
    <AvatarImage src="/avatar-1.jpg" alt="User 1" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/avatar-2.jpg" alt="User 2" />
    <AvatarFallback>EB</AvatarFallback>
  </Avatar>
  ...
</AvatarGroup>
JDEBMK+2
<AvatarGroup max={3}>
  <Avatar>
    <AvatarImage src="/avatar-1.jpg" alt="User 1" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  ...{/* 5 avatars total */}
</AvatarGroup>

API

Component Structure

Avatar— Radix Avatar
.ImageProps.FallbackProps.GroupProps

Props

Avatar

size"default"
"xs" | "sm" | "default" | "lg" | "xl" | "2xl"

Avatar size (24/32/40/48/64/80px)

shape"circle"
"circle" | "square"

Shape (circle / rounded square)

statusundefined
"online" | "offline" | "busy" | "away"

Status dot indicator

AvatarImage

srcundefined
string

Image URL

altundefined
string

Alternative text for the image

onLoadingStatusChangeundefined
(status: "idle" | "loading" | "loaded" | "error") => void

Callback for loading status changes

AvatarFallback

size"default"
"xs" | "sm" | "default" | "lg" | "xl" | "2xl"

For font size scaling

nameundefined
string

Auto-generates initials and color from name. Overrides initials if children are provided

colorizedundefined
string

Auto-applies color only (initials manual). name takes precedence if provided

colorVariant"vivid"
"vivid" | "soft"

Color style: vivid (dark background + white text) / soft (light background + dark text)

delayMsundefined
number

Delay before showing fallback (ms)

AvatarGroup

maxundefined
number

Maximum number shown. Excess displayed as "+N"

size"default"
"xs" | "sm" | "default" | "lg" | "xl" | "2xl"

Child avatar size (applied to "+N" badge)

shape"circle"
"circle" | "square"

Child avatar shape (applied to "+N" badge)

Customization

Pass the name prop to auto-generate initials and a color.

name prop — Auto initials + color

JD
John
EB
Emma
MK
Michael
RS
Rachel
TW
Tina
<AvatarFallback name="John Doe" /> {/* → "JD" + color */} <AvatarFallback name="Emma Brown" /> {/* → "EB" + color */}

Vivid vs Soft

Vivid (default)

Google / Slack / Teams

JDEBMKRSTW
<AvatarFallback name={name} />
Soft

Notion / Linear

JDEBMKRSTW
<AvatarFallback name={name} colorVariant="soft" />

CJK Support

김민
김민수
→ "김민"
田中
田中太郎
→ "田中"
李明
李明
→ "李明"
<AvatarFallback name="김민수" /> <AvatarFallback name="田中太郎" /> <AvatarFallback name="李明" />

Image + Fallback

JD
With image
JD
Fallback
<Avatar> <AvatarImage src={url} alt={name} /> <AvatarFallback name={name} /> </Avatar>

Tip：The same name always produces the same color (deterministic hash). Pass children to override auto-generated initials.

Anatomy

1
2
HJ
3
1
Container
Circular container
2
Image / Initials
Image or fallback
3
Status Indicator
Status dot (optional)

Best Practices

✓

Do

  • ✓Always provide alt text
  • ✓Always pair AvatarImage with a fallback
  • ✓Use consistent sizes within a group
  • ✓Use status only where it carries meaning
✕

Don't

  • ✗Don't use image avatars without alt text
  • ✗Don't use AvatarImage without a fallback
  • ✗Don't mix sizes within a group
  • ✗Don't use avatars for purely decorative purposes

Accessibility

Keyboard

TabMove focus

ARIA / WCAG

  • role="img" Auto-applied by Radix
  • alt Describes image via alt text
  • Fallback provides text alternative
  • Status dot is decorative (supplement with text)