Skip to Content
ComponentsFoundationAvatar

Avatar

사용자 프로필 이미지나 이니셜을 표시하는 컴포넌트

개요

Avatar 컴포넌트는 base-ui의 Avatar Primitive를 기반으로 사용자를 나타내는 프로필 이미지를 표시합니다. 이미지 로딩 실패 시 이니셜이나 아이콘으로 대체할 수 있는 Fallback을 제공합니다.

주요 특징

  • ✅ 크기 옵션: sm, default, lg 사이즈 지원
  • ✅ Fallback 처리: 이미지 로딩 실패 시 자동 대체 표시
  • ✅ 상태 배지: AvatarBadge로 온라인 상태 등 표시 가능
  • ✅ 그룹 표시: AvatarGroup, AvatarGroupCount로 여러 사용자 나열
  • ✅ 시맨틱 마크업: base-ui Avatar 기반 접근성 지원
  • ✅ 디자인 토큰: CSS 변수 기반 테마 커스터마이징 지원

사용 예시

기본 사용법

AvatarImage와 AvatarFallback을 조합합니다.

홍길동김철수

Sizes

Avatar는 3가지 크기를 지원합니다.

SMMDLG

Size 설명

Size설명사용 사례
sm작은 크기댓글, 목록 내 보조 표시
default기본 크기일반적인 프로필 표시
lg큰 크기프로필 페이지, 강조 표시

상태 배지

AvatarBadge로 온라인 상태 등을 표시할 수 있습니다.

홍길동오프라인

아바타 그룹

AvatarGroup으로 여러 사용자를 겹쳐서 표시하고, AvatarGroupCount로 나머지 인원을 나타냅니다.

1김이
+3

API Reference

Avatar Props

PropTypeDefaultDescription
size"sm" | "default" | "lg""default"아바타 크기
classNamestring-추가 CSS 클래스

AvatarImage Props

base-ui Avatar.Image의 props를 지원합니다.

PropTypeDefaultDescription
srcstring-이미지 URL
altstring-대체 텍스트
classNamestring-추가 CSS 클래스

AvatarFallback Props

base-ui Avatar.Fallback의 props를 지원합니다. 이미지 로딩 전이나 실패 시 표시됩니다.

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

AvatarBadge Props

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

AvatarGroup / AvatarGroupCount Props

PropTypeDefaultDescription
classNamestring-추가 CSS 클래스

기본 사용법

import { Avatar, AvatarImage, AvatarFallback } from "@vortex/ui-foundation"
 
<Avatar>
  <AvatarImage src="/profile.jpg" alt="사용자" />
  <AvatarFallback>홍</AvatarFallback>
</Avatar>

접근성

base-ui Avatar 기반

  • 이미지의 alt 텍스트로 사용자 정보를 전달합니다
  • Fallback은 이미지 로딩 실패 시에도 사용자 식별이 가능하도록 이니셜을 제공합니다

권장 사항

  • ✅ AvatarImage에 사용자 이름이 포함된 alt 제공
  • ✅ Fallback은 이름 이니셜 등 식별 가능한 텍스트 사용
  • ✅ AvatarBadge의 색상만으로 상태를 전달하지 말고, 필요시 텍스트 레이블 병행

관련 컴포넌트

  • Badge: 상태를 나타내는 작은 표시기
  • AspectRatio: 이미지 비율 유지 컨테이너
  • Image: 로딩/에러 처리 이미지 컴포넌트
Last updated on
AspectRatioBadge