アバターAvatarBeta
ユーザーを表す画像で、フォールバック付きです。
プレビュー
状態とバリエーション
画像あり
プロフィール画像がある場合は AvatarImage を表示し、読み込み失敗時にフォールバックへ戻します。
青
フォールバック
画像がない場合でも、イニシャルやアイコンで誰の情報か判断できるようにします。
田
在席表示との合成
在席状態を付ける場合は、色だけでなくツールチップでも状態を確認できるようにします。
青
プロパティ
表は横にスクロールできます
| プロパティ | 型 | 初期値 | 説明 |
|---|---|---|---|
| Avatar | React.ComponentProps<typeof AvatarPrimitive.Root> | - | 画像とフォールバックを包むルート要素です。 |
| AvatarImage.src | string | - | 表示する画像の URL です。 |
| AvatarImage.alt | string | - | 画像自体が意味を持つ場合の代替テキストです。 |
| Avatar.tooltip | ReactNode | - | ホバー時に表示する名前や補足情報です。 |
| Avatar.tooltipPortalContainer | HTMLElement | null | - | パターンの擬似ブラウザ内など、ツールチップを描画するコンテナです。 |
| Avatar.presence | "online" | "away" | "busy" | "offline" | - | 在席状態を示す小さなステータス点です。 |
| Avatar.presenceLabel | ReactNode | - | 在席状態をツールチップや支援技術へ伝えるラベルです。 |
| AvatarFallback.children | ReactNode | - | 画像が読み込めない時に表示する文字やアイコンです。 |
| AvatarFallback.colorSeed | string | - | 任意。名前などのシードをハッシュして、コントラスト安全なトーン対の1つに決定的に着色します（同じシード＝同じ色）。名簿など密な一覧の走査性向上に。既定はグレー。色は装飾（状態ではない）。(#331) |
使い方
import { Avatar, AvatarFallback, AvatarImage } from "@gunjo/ui";
export function UserAvatar() {
return (
<Avatar
aria-label="青井 花"
tooltip="青井 花"
presence="online"
presenceLabel="オンライン"
>
<AvatarImage src="/samples/avatar-aoi.svg" alt="" />
<AvatarFallback>青</AvatarFallback>
</Avatar>
);
}設計の判断
- 色は身元の目印であって、状態ではない。
AvatarFallbackのcolorSeedに名前などを渡すと、決まった計算で同じ色に落ちます。同じ名前なら常に同じ色です。頭文字が並んだときに全部同じ灰色になるのを避けるためのもので、色は身元の手がかりであって良し悪しを意味しません（#331）。色は背景と文字の組でトークンから取るので、明るいテーマでも暗いテーマでも読めます。 - 在席の点は、文言を渡したときだけ読み上げに乗る。
presenceの点は色だけの表現です。そこでpresenceLabelを渡したときは点にaria-labelが付き、渡さないときはaria-hiddenになります。色が見えない人にも伝えたいなら文言を渡す、という分かれ道を明示にしてあります。見本ではtooltipにも名前と在席を一緒に入れています。 - 丸だけで誰か分からないときは、名前を添えられるようにする。
tooltipを渡すと、アバター全体がツールチップのトリガーになります。画像が読めなかったときに頭文字へ落とす切り替えは Radix のAvatarが持っているので、こちらでは書いていません。頭文字を何文字にするか、並べるときの上限をいくつにするかは資料に書いてあります。
使用コンポーネント
関連コンポーネント
いつ・なぜ使うか（UIXHERO）
「いつ・なぜ使うか」の判断は、姉妹サイト UIXHERO の記事で解説しています。