7onicDESIGN SYSTEM

Avatar

Avatar는 사용자나 엔티티를 시각적으로 나타내는 컴포넌트입니다. 이미지, 이니셜, 아이콘 폴백을 지원하며 상태 표시와 그룹 표시에도 대응합니다.

2
Shapes
6
Sizes
4
Status
Radix
Base

Playground

미리보기
D
JD
Size
Shape
Content
Options
Status
<Avatar>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

Sizes

xs
크기24px
폰트10px
점6px
sm
크기32px
폰트12px
점8px
default
크기40px
폰트14px
점10px
lg
크기48px
폰트16px
점12px
xl
크기64px
폰트20px
점14px
2xl
크기80px
폰트24px
점16px

Features

Shapes

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

Status

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

Fallback

이미지를 불러오지 못할 경우 이니셜 또는 아이콘이 폴백으로 표시됩니다.

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

{/* Initials only */}
<Avatar>
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

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

Avatar Group

여러 아바타를 겹쳐서 표시합니다. max로 표시 수를 제한할 수 있습니다.

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

API

Component Structure

Avatar— Radix Avatar
.ImageProps.FallbackProps.GroupProps

Props

Avatar

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

아바타 크기 (24/32/40/48/64/80px)

shape"circle"
"circle" | "square"

모양 (원형/둥근 정사각형)

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

상태 도트 표시

Avatar.Image

srcundefined
string

이미지 URL

altundefined
string

이미지 대체 텍스트

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

로딩 상태 변경 콜백

Avatar.Fallback

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

폰트 크기 스케일링용

nameundefined
string

이름에서 이니셜+색상 자동 생성. children이 있으면 이니셜 덮어쓰기

colorizedundefined
string

색상만 자동 적용 (이니셜은 수동). name이 있으면 name 우선

colorVariant"vivid"
"vivid" | "soft"

색상 스타일: vivid (진한 배경+흰 글자) / soft (연한 배경+진한 글자)

delayMsundefined
number

폴백 표시 지연 시간 (ms)

Avatar.Group

maxundefined
number

최대 표시 수. 초과분은 "+N"으로 표시

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

자식 아바타 크기 ("+N" 뱃지에 적용)

shape"circle"
"circle" | "square"

자식 아바타 모양 ("+N" 뱃지에 적용)

Customization

name prop만 전달하면 이니셜과 색상을 자동 생성합니다.

name prop: 이니셜, 색상 자동 생성

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

Vivid vs Soft

Vivid (default)

Google / Slack / Teams

JDEBMKRSTW
<Avatar.Fallback name={name} />
Soft

Notion / Linear

JDEBMKRSTW
<Avatar.Fallback name={name} colorVariant="soft" />

CJK 지원

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

이미지 + 폴백

JD
이미지 있음
JD
폴백
<Avatar> <Avatar.Image src={url} alt={name} /> <Avatar.Fallback name={name} /> </Avatar>

Tip：같은 name은 항상 같은 색상이 됩니다 (결정론적 해시). children을 전달하면 자동 이니셜을 덮어쓸 수 있습니다.

Anatomy

1
2
HJ
3
1
Container
원형 컨테이너
2
Image / Initials
이미지 또는 폴백
3
Status Indicator
상태 도트 (선택)

Best Practices

✓

권장

  • ✓반드시 alt 텍스트를 설정하세요
  • ✓이미지에는 반드시 폴백을 준비하세요
  • ✓그룹에서는 일관된 크기를 사용하세요
  • ✓상태는 의미 있는 상황에서만 사용하세요
✕

지양

  • ✗alt 텍스트 없이 이미지 아바타를 사용하지 마세요
  • ✗폴백 없이 Avatar.Image를 사용하지 마세요
  • ✗그룹 내에서 크기를 혼용하지 마세요
  • ✗장식 목적으로만 아바타를 사용하지 마세요

Accessibility

키보드 조작

Tab포커스 이동

ARIA / WCAG

  • role="img" Radix 자동 적용
  • alt alt 텍스트로 이미지 설명
  • 폴백으로 텍스트 대체 제공
  • 상태 도트는 장식적 요소 (별도 텍스트로 보완 권장)