Avatar

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

개요

iCignal Avatar는 Foundation Avatar를 래핑하여 이미지(src)와 폴백(fallback, name)을 하나의 컴포넌트로 간편하게 사용할 수 있도록 한 컴포넌트입니다. 이미지 로딩에 실패하거나 src가 없으면 이니셜 폴백이 자동으로 표시됩니다. AvatarBadge, AvatarGroup, AvatarGroupCount 등 Foundation 서브컴포넌트도 함께 제공합니다.

주요 특징

• ✅ 이미지 + 폴백 통합: src와 fallback을 props로 한 번에 지정
• ✅ 자동 이니셜: name의 앞 2글자를 자동으로 폴백 텍스트로 사용
• ✅ 3단계 크기: sm, default, lg 크기 지원
• ✅ 뱃지 지원: AvatarBadge로 온라인 상태 등 표시
• ✅ 그룹 지원: AvatarGroup, AvatarGroupCount로 여러 사용자 표시
• ✅ 안전한 이미지 로딩: src가 없을 때 이미지 엘리먼트 미마운트로 오류 방지

Sizes

<Avatar size="sm" name="홍길동" />
<Avatar size="default" name="홍길동" />
<Avatar size="lg" name="홍길동" />

사용 예시

이미지 표시

src로 프로필 이미지를 표시하고, name으로 대체 텍스트와 폴백 이니셜을 지정합니다.

<Avatar src="https://picsum.photos/100/100" name="홍길동" />
<Avatar src="https://picsum.photos/100/100" name="김영희" />

폴백 이니셜

src가 없거나 이미지 로딩에 실패하면 name의 앞 2글자가 폴백으로 표시됩니다.

<Avatar name="홍길동" />
<Avatar name="김영희" />
{/* 이미지 로딩 실패 시에도 폴백 표시 */}
<Avatar src="https://invalid-url/broken.jpg" name="이철수" />

커스텀 폴백

fallback prop으로 이니셜 대신 원하는 텍스트를 표시할 수 있습니다.

<Avatar name="홍길동" fallback="GD" />
<Avatar fallback="?" />

뱃지 표시

AvatarBadge로 온라인 상태 등을 우하단에 표시합니다.

<Avatar src="https://picsum.photos/100/100" name="온라인 사용자">
  <AvatarBadge />
</Avatar>
<Avatar size="lg" name="김영희">
  <AvatarBadge />
</Avatar>

아바타 그룹

AvatarGroup으로 여러 아바타를 겹쳐 표시하고, AvatarGroupCount로 나머지 인원을 표시합니다.

<AvatarGroup>
  <Avatar src="https://picsum.photos/100/100" name="사용자 1" />
  <Avatar name="김영희" />
  <Avatar name="이철수" />
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>

API Reference

Props

서브컴포넌트

기본 사용법

import { Avatar, AvatarBadge, AvatarGroup, AvatarGroupCount } from "@vortex/ui-icignal"
 
<Avatar src="/profile.jpg" name="홍길동" />
<Avatar name="홍길동" size="lg">
  <AvatarBadge />
</Avatar>
 
<AvatarGroup>
  <Avatar src="/user1.jpg" name="사용자 1" />
  <Avatar name="김영희" />
  <AvatarGroupCount>+5</AvatarGroupCount>
</AvatarGroup>

접근성

권장 사항

• ✅ name prop으로 이미지의 대체 텍스트(alt)를 제공
• ✅ 이미지 로딩 실패 시 폴백이 자동 표시되므로 항상 의미 있는 name 전달
• ✅ AvatarBadge만으로 상태를 전달하지 말고 텍스트 레이블 병행 고려
• ❌ 장식 목적이 아닌 경우 빈 폴백 지양

관련 컴포넌트

• Avatar (Foundation): Foundation 레이어 아바타
• Badge (Foundation): 상태 표시 뱃지
• Image (Foundation): 일반 이미지 컴포넌트