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 テキストで画像説明
  • フォールバックでテキスト代替を提供
  • ステータスドットは装飾的 (別途テキストで補完推奨)