Avatar

fandhe-frontend-pre-styled-ui の avatar mod が提供するスタイル済み Avatar 部品です。

ユーザーやチームの識別に使うアイコン画像・イニシャル表示部品です。ImageStatus（Loading/Loaded/Error）に応じて image パーツと fallback パーツの表示・非表示を CSS の data-state セレクタで切り替えます。

size（Xs〜Xl）・shape（Circle/Rounded/Square）・variant（Subtle/Solid/Outline）・colorPalette（6 値、既定 Neutral）の 4 軸を持ちます（イシュー #1554 で参照サイト〔chakra-ui/Radix Themes〕基準へ調整）。

イシュー #2044 で shadcn/ui と突合し、group（複数の Avatar を重ねて表示するレイアウト専用パート）と badge（右下に配置する状態ドット）を pre-styled- only パートとして補完しました。group は stacked: true にした Avatar を並べて重なり表示を作り、残数表示（+N）は独立したパートを新設せず root(stacked) + fallback("+3") の組み合わせで表現します。badge は with_badge: true にした Avatar の右下へ絶対配置され、AvatarBadgeProps で size（既定 Md）・palette（既定 Accent）を指定します。

Avatar の Demo は ImageStatus を固定し、画像読み込み成功時の表示とフォールバック（イニシャル等）表示の両方、variant・colorPalette の組み合わせ、および group/badge の合成パターンを掲示しています。

イシュー #3130 で 3 点を opt-in で追加しました。badge は AvatarBadgeProps::placement（AvatarBadgePlacement、既定 BottomEnd）で右下/右上を切り替えられます。group の重なり順は group_with + AvatarGroupProps（AvatarGroupStacking、既定 LastOnTop=DOM 順）で、FirstOnTop にすると先頭の Avatar が最前面になります（既存の group はシグネチャ・出力とも変更していません）。共通 Size enum（最大 56px）を超える大サイズは新規 API を追加せず、root 呼び出し側の attrs へ inline style を渡して上書きします。

Demo

size（Xs〜Xl）・shape（Circle/Rounded/Square）・variant（Subtle/Solid/Outline）・colorPalette（6 値）の 4 軸を持つユーザー画像表示。画像読み込み状態（ImageStatus）を固定し、Error 時はイニシャルのフォールバック表示、Loaded 時は画像表示を掲示します。イシュー #2044（shadcn/ui 突合）で重なり表示 + +N（group）と右下の状態ドット（badge）を追加しました。

Size

Shape

Variant

Palette

Features

AvatarShape（Circle/Rounded/Square、crates/pre-styled-ui/src/avatar.rs）で外形を切り替える
AvatarVariant（Subtle/Solid/Outline、イシュー #1554 で追加）で見た目バリアントを切り替える
ColorPalette（6 値、既定 Neutral、イシュー #1554 で追加）で colorPalette 軸を切り替える
ImageStatus に連動して image/fallback パーツの表示・非表示を CSS の [data-state="hidden"] で切り替える
image パーツは alt テキストを必須引数として要求する（avatar.rs 内 image 再エクスポート）
group（イシュー #2044）で複数 root を重なり表示し、+N の残数表示は root(stacked) + fallback の組み合わせで表現する
badge（イシュー #2044）で root 右下に状態ドットを絶対配置し、with_badge: true の root のみ overflow を解除する
AvatarBadgePlacement（BottomEnd/TopEnd、イシュー #3130）で badge の配置を右下/右上へ切り替える
group_with + AvatarGroupStacking（LastOnTop/FirstOnTop、イシュー #3130）で group 内の重なり順（先頭を最前面にするか）を切り替える
共通 Size enum（最大 56px）を超える大サイズは root の呼び出し側 attrs へ inline style を渡して上書きする（イシュー #3130、新規公開 API なし）

Anatomy

root
  image
  fallback
group
  badge

API Reference

Arguments

Name	Type	Default	Description
`size`	`Size`	`Md`	サイズ（avatar.rs の AvatarProps、#[default] は Md。イシュー #1554 で 24/32/40/48/56px へ是正）。
`shape`	`AvatarShape`	`Circle`	外形（avatar.rs の AvatarShape、#[default] は Circle）。
`variant`	`AvatarVariant`	`Subtle`	見た目バリアント（avatar.rs の AvatarVariant、#[default] は Subtle。イシュー #1554 で追加）。
`palette`	`ColorPalette`	`Neutral`	colorPalette 軸（avatar.rs の AvatarProps、#[default] は Neutral。イシュー #1554 で追加）。
`stacked`	`bool`	`false`	group 内で重なり表示するか（avatar.rs の AvatarProps、イシュー #2044 で追加）。
`with_badge`	`bool`	`false`	badge を子に持つか（avatar.rs の AvatarProps、イシュー #2044 で追加。true のときのみ overflow: visible を解除する）。
`group()`	`fn`	—	pre-styled-only group パート（avatar.rs、イシュー #2044）。headless-ui の anatomy には存在しない。
`badge()`	`fn`	—	pre-styled-only badge パート（avatar.rs、イシュー #2044）。AvatarBadgeProps（size: Md、palette: Accent）を取る。
`AvatarBadgeProps`	`struct`	`size: Md, palette: Accent, placement: BottomEnd`	badge() の設定（avatar.rs、イシュー #2044。size は Xs〜Xl の 5 段、palette は ColorPalette 6 値。placement はイシュー #3130 で追加）。
`placement`	`AvatarBadgePlacement`	`BottomEnd`	badge の配置（avatar.rs の AvatarBadgeProps、#[default] は BottomEnd。イシュー #3130 で追加、TopEnd で右上へ移る）。
`group_with()`	`fn`	—	pre-styled-only group パートの拡張版（avatar.rs、イシュー #3130）。AvatarGroupProps を取り、stacking: LastOnTop（既定）のときは group() と出力が完全一致する。
`AvatarGroupProps`	`struct`	`stacking: LastOnTop`	group_with() の設定（avatar.rs、イシュー #3130）。
`stacking`	`AvatarGroupStacking`	`LastOnTop`	group 内の重なり順（avatar.rs の AvatarGroupProps、#[default] は LastOnTop=DOM 順。イシュー #3130 で追加、FirstOnTop で先頭の root が最前面になる）。

Data Attributes

Part	Attribute	Observed Values
`fallback`	`data-state`	`hidden`, `visible`
`image`	`data-state`	`hidden`, `visible`

Examples

Fallback

画像読み込み失敗（ImageStatus::Error）時のイニシャル表示例です。

重なり表示 + +N

group + stacked root 2 個 + +3 の fallback を組み合わせた重なり表示の例です（イシュー #2044）。

状態 badge

with_badge: true の root の右下に badge（既定 Accent）を重ねた例です（イシュー #2044）。

badge を右上へ

AvatarBadgePlacement::TopEnd で badge を右上へ移した例です（イシュー #3130）。

先頭を最前面に重ねる

group_with + AvatarGroupStacking::FirstOnTop で先頭の root を最前面にした例です（イシュー #3130）。

大サイズ（56px 超）

共通 Size enum を超える大サイズを inline style の上書きで表現した例です（イシュー #3130、新規公開 API なし）。

Accessibility

WAI-ARIA

Attribute	Description
(該当なし)	root/image/fallback/group/badge は固有の role/aria-* を出力しない（avatar.rs 全文で role/aria-* を grep しても 0 件）。image パーツの alt テキストが代替情報を提供する。badge は装飾のためアクセシブルネームを持たず、必要な場合は呼び出し側が root の aria-label 等で供給する（イシュー #2044）。