Avatar 아바타

LhAvatar는 사용자나 사물의 아바타를 표시하며, 이미지, 아이콘, 글자 세 가지 형태를 지원하고 이미지 로드에 실패하면 자동으로 폴백합니다.

기본 사용법

이미지 아바타

fit으로 자르기 모드(네이티브 object-fit)를 제어하고, alt로 대체 텍스트를 제공합니다.

<script setup lang="ts">
</script>

<template>
  <!-- 이미지 아바타 -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit 자르기 + alt 대체 텍스트 -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="사용자 아바타"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- 이미지 아바타 -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit 자르기 + alt 대체 텍스트 -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="사용자 아바타"
  />
</template>

모양과 크기

원형과 사각형, 네 가지 크기

소중대원

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="소"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="중"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="대"
    />
    <LhAvatar
      size="large"
      text="원"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="소"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="중"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="대"
    />
    <LhAvatar
      size="large"
      text="원"
    />
  </div>
</template>

글자와 아이콘 폴백

이미지가 없을 때 icon, text 순서로 폴백

수A

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="수묵" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="수묵" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

글자 아바타는 자동으로 첫 글자를 추출해 표시합니다(한자는 첫 글자, 알파벳은 대문자 첫 글자).

이미지 로드 실패

실패 후 text로 폴백하고 error 이벤트 발생

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="대체"
    @error="onError"
  />
</template>

<script setup lang="ts">
function onError(e: Event) {
  console.log('avatar load error', e)
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="대체"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onError(e) {
      console.log('avatar load error', e)
    },
  },
}
</script>

API

Props

속성	설명	타입	기본값
src	이미지 주소, 비어 있으면 아이콘/글자로 폴백	string	—
alt	대체 텍스트	string	—
icon	아이콘 이름(내장 LhIcon 아이콘, src가 없을 때 표시)	LhIconName	—
text	글자 내용(src와 icon이 없을 때 첫 글자를 추출해 표시)	string	—
shape	아바타 모양	"circle" | "square"	'circle'
size	아바타 크기	"small" | "medium" | "large" | "mini" | "x-large"	'medium'
fit	이미지 로드 모드: fill / contain / cover	"fill" | "contain" | "cover" | "none" | "scale-down"	'cover'
sx	sx 빠른 레이아웃 속성	LhSxProps	—

Events

이벤트	설명	콜백 매개변수
error	이미지 로드 실패 시 발생	(e: Event)

접근성

• 이미지 모드는 <img alt> 자체가 대체 텍스트를 제공합니다. alt를 전달하지 않으면 text로, 그다음 avatar로 폴백합니다
• 아이콘/글자 모드는 루트 요소가 role="img"를 담당하며, alt를 전달하면 접근성 이름으로 사용됩니다. 아이콘 자체는 aria-hidden으로 표시됩니다

타입 정의

이 컴포넌트가 외부로 내보내는 TypeScript 타입 구조는 다음과 같습니다(packages/components/avatar/src/types.ts와 @lh-ui/share/core/* 소스에서 자동 추출, 각 항목을 펼쳐 전체 정의를 확인하세요. 속성 설명은 위쪽 Props 표를 참고하세요).

LhAvatarProps

export interface LhAvatarProps {
  /** 이미지 주소. 비어 있으면 아이콘, 글자 순서로 폴백 */
  src?: string
  /** 이미지 로드 실패 시 대체 텍스트, alt로도 사용 */
  alt?: string
  /** 아이콘 이름(src가 비어 있거나 로드 실패 시 표시, 내장 LhIcon 아이콘 사용) */
  icon?: LhIconName
  /** 글자 아바타 내용(src와 icon 모두 없을 때 첫 글자를 추출해 표시) */
  text?: string
  /** 아바타 모양 */
  shape?: LhAvatarComponentShape
  /** 아바타 크기 */
  size?: LhAvatarSize
  /** 이미지 로드 모드: fill / contain / cover */
  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
  /** sx 빠른 레이아웃 속성 */
  sx?: LhSxProps
}

LhAvatarSize

export type LhAvatarSize = LhComponentSize

LhAvatarShape

export type LhAvatarShape = LhAvatarComponentShape

LhAvatarComponentShape _{(@lh-ui/share/core/avatar에서 가져옴)}

export type LhAvatarShape = 'circle' | 'square'

LhIconName _{(@lh-ui/share/core/icon (svgs.ts)에서 가져옴)}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

LhComponentSize _{(@lh-ui/share/core/shared에서 가져옴)}

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]