Avatar
먼저 보고, 그다음 계약을 읽습니다
user/agent 신원 배지 — 이미지 실패 시 initials 폴백.
Component intent의도와 경계 읽기
ChatMessage 의 sender, AgentInbox 의 agent 신원, 온보딩 프로필 placeholder 등 신원 표시의 표준. Radix Avatar 를 감싸 이미지 로드 실패/미지정 시 Fallback(initials)을 보여준다. 원형 표면에 sm/md/lg 세 크기(24/32/48px)를 제공하며, Fallback 의 delayMs 로 빠른 로드 시 initials 깜빡임(LCP 저해)을 억제한다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { Avatar, AvatarImage, AvatarFallback } from "@axe/ui";<Avatar size="md"> <AvatarImage src="/u/axe.png" alt="강수훈" /> <AvatarFallback delayMs={300}>강</AvatarFallback></Avatar>import { Avatar, AvatarFallback } from "@axe/ui";<Avatar size="lg"> <AvatarFallback>AX</AvatarFallback></Avatar><!-- 이미지가 확실할 때 --><span class="axe-avatar axe-avatar--md"> <img class="axe-avatar__image" src="/u/axe.png" alt="강수훈" /></span><!-- 이니셜만 --><span class="axe-avatar axe-avatar--lg"> <span class="axe-avatar__fallback">AX</span></span>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
Avatar.size | "sm" | "md" | "lg" | — | "md" | 크기 — sm 24 / md 32 / lg 48px(폰트 크기 동반). |
Avatar.…rest | React.ComponentPropsWithoutRef<Radix Avatar.Root> | — | — | className 은 axe-avatar 와 병합, 나머지는 Radix Root 로 전파. |
AvatarImage.…rest | React.ComponentPropsWithoutRef<Radix Avatar.Image> | — | — | src/alt 등. 로드 실패/지연 시 Fallback 이 대신 노출. 나머지는 Radix Image 로 전파. |
AvatarFallback.delayMs | number | — | — | 이 ms 만큼 지연 후 fallback 표시 — 빠른 이미지 로드 시 initials 깜빡임 방지(Radix). |
AvatarFallback.…rest | React.ComponentPropsWithoutRef<Radix Avatar.Fallback> | — | — | children=initials 등. className 은 axe-avatar__fallback 과 병합, 나머지는 Radix Fallback 으로 전파. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-avatar | stable | 루트 — 원형(border-radius 9999px) inline-flex, overflow hidden, bg-subtle. |
.axe-avatar--sm | stable | 24×24px(폰트 10px). |
.axe-avatar--md | stable | 32×32px(폰트 12px, 기본). |
.axe-avatar--lg | stable | 48×48px(폰트 18px). |
.axe-avatar__image | stable | 이미지 — object-fit:cover, 원형 상속. |
.axe-avatar__fallback | stable | initials 폴백 — 중앙 정렬, uppercase, bg-subtle. |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
이미지에는 의미 있는 alt 를 지정한다(빈 alt=순수 장식). Fallback 의 initials 는 스크린리더에서 이름을 대체하지 못하므로, 사람 이름 같은 의미는 AvatarImage 의 alt 나 인접 텍스트로 제공해야 한다.
Radix Avatar 가 이미지 로드 상태를 관리 — 실패/미지정 시 Fallback 으로 전환하고 delayMs 로 초기 깜빡임을 억제한다. 자체 포커스/role 은 없다(순수 표시). 클릭 대상이면 <button>/<a> 로 감싼다.