Avatar

사용자 프로필 이미지를 표시하는 아바타 컴포넌트입니다.

개요

Avatar는 사용자를 시각적으로 나타내는 컴포넌트로, 프로필 이미지 또는 이니셜을 표시합니다. 이미지 로딩 실패 시 Fallback을 제공하며, 여러 아바타를 그룹으로 표시할 수도 있습니다.

주요 특징:

이미지 아바타
이니셜 아바타
4가지 Size (sm, md, lg, xl)
Fallback 처리
아바타 그룹 지원

사용 사례:

사용자 프로필
댓글 작성자 표시
팀 멤버 목록
사용자 선택 UI

설치


npx @vortex/cli add avatar --package foundation

기본 사용법


import { Avatar } from "@vortex/ui-foundation";
 
export default function Example() {
  return <Avatar src="/avatar.jpg" alt="User Name" />;
}

Variants (변형)

이미지 아바타


<Avatar src="https://example.com/avatar.jpg" alt="John Doe" />

이니셜 아바타


<Avatar>JD</Avatar>

Fallback 처리

이미지 로딩 실패 시 자동으로 이니셜 또는 기본 아이콘으로 표시됩니다.


<Avatar src="/invalid-url.jpg" fallback="JD" alt="John Doe" />

Sizes (크기)

Small


<Avatar size="sm" src="/avatar.jpg" />

Medium (기본)


<Avatar size="md" src="/avatar.jpg" />

Large


<Avatar size="lg" src="/avatar.jpg" />

Extra Large


<Avatar size="xl" src="/avatar.jpg" />

아바타 그룹

여러 아바타를 겹쳐서 표시합니다.


<AvatarGroup max={3}>
  <Avatar src="/user1.jpg" alt="User 1" />
  <Avatar src="/user2.jpg" alt="User 2" />
  <Avatar src="/user3.jpg" alt="User 3" />
  <Avatar src="/user4.jpg" alt="User 4" />
</AvatarGroup>

Props API

Prop	Type	Default	Description
src	string	-	이미지 URL
alt	string	-	대체 텍스트 (필수)
fallback	string	-	Fallback 텍스트 (이니셜)
size	’sm’ \| ‘md’ \| ‘lg’ \| ‘xl'	'md’	아바타 크기
className	string	-	추가 CSS 클래스
children	ReactNode	-	이니셜 텍스트

접근성

Avatar 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다.

ARIA 속성:

alt 속성 필수 (이미지 아바타)
aria-label (이니셜 아바타)

스크린 리더 지원:

이미지 설명 제공
사용자 이름 명확하게 읽힘

예제

예제 1: 사용자 프로필


export default function UserProfile() {
  return (
    <div className="flex items-center gap-md">
      <Avatar size="lg" src="/profile.jpg" alt="홍길동" />
      <div>
        <h3>홍길동</h3>
        <p className="text-sm text-gray-600">hong@example.com</p>
      </div>
    </div>
  );
}

예제 2: 팀 멤버 목록


export default function TeamMembers() {
  const members = [
    { name: "김철수", initials: "KC", image: "/kim.jpg" },
    { name: "이영희", initials: "LY", image: "/lee.jpg" },
    { name: "박민수", initials: "PM", image: "/park.jpg" },
  ];
 
  return (
    <div className="flex gap-sm">
      {members.map((member) => (
        <Avatar
          key={member.name}
          src={member.image}
          fallback={member.initials}
          alt={member.name}
        />
      ))}
    </div>
  );
}