# Avatar
URL: /docs/components/avatar
Source: https://raw.githubusercontent.com/goorm-dev/vapor-ui/refs/heads/main/apps/website/content/docs/components/(components)/avatar.mdx

Avatar는 사용자가 설정한 프로필 이미지 혹은 텍스트를 UI상에 나타냅니다.

***

title: 'Avatar'
site\_name: 'Avatar - Vapor Core'
description: 'Avatar는 사용자가 설정한 프로필 이미지 혹은 텍스트를 UI상에 나타냅니다.'
-----------------------------------------------------------

<Demo name="avatar/default-avatar">
  ```tsx
  import { Avatar } from '@vapor-ui/core';

  import { VAPOR_LOGO_URL } from '~/constants/image-urls';

  export default function DefaultAvatar() {
      return <Avatar.Root alt="Vapor" src={VAPOR_LOGO_URL} />;
  }

  ```
</Demo>

## Property

***

### Shape

Avatar의 모양을 설정합니다.

<Demo name="avatar/avatar-shape">
  ```tsx
  import { Avatar, HStack, Text, VStack } from '@vapor-ui/core';

  import { VAPOR_LOGO_URL } from '~/constants/image-urls';

  export default function AvatarShape() {
      return (
          <VStack $css={{ gap: '$150' }}>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-14" typography="body3" foreground="hint-100">
                      square
                  </Text>
                  <Avatar.Root shape="square" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-14" typography="body3" foreground="hint-100">
                      circle
                  </Text>
                  <Avatar.Root shape="circle" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
          </VStack>
      );
  }

  ```
</Demo>

### Size

Avatar의 크기를 설정합니다.

<Demo name="avatar/avatar-size">
  ```tsx
  import { Avatar, HStack, Text, VStack } from '@vapor-ui/core';

  import { VAPOR_LOGO_URL } from '~/constants/image-urls';

  export default function AvatarSize() {
      return (
          <VStack $css={{ gap: '$150' }}>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-6" typography="body3" foreground="hint-100">
                      sm
                  </Text>
                  <Avatar.Root size="sm" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-6" typography="body3" foreground="hint-100">
                      md
                  </Text>
                  <Avatar.Root size="md" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-6" typography="body3" foreground="hint-100">
                      lg
                  </Text>
                  <Avatar.Root size="lg" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-6" typography="body3" foreground="hint-100">
                      xl
                  </Text>
                  <Avatar.Root size="xl" alt="Vapor" src={VAPOR_LOGO_URL} />
              </HStack>
          </VStack>
      );
  }

  ```
</Demo>

## Examples

***

### Fallback

이미지가 없거나 로드에 실패한 경우, alt 텍스트의 첫 글자가 자동으로 표시됩니다. 배경색은 alt 문자열을 기반으로 결정됩니다.

<Demo name="avatar/avatar-fallback">
  ```tsx
  import { Avatar, HStack } from '@vapor-ui/core';

  export default function AvatarFallback() {
      return (
          <HStack $css={{ gap: '$150', alignItems: 'center' }}>
              <Avatar.Root alt="John Doe" />
              <Avatar.Root alt="Alice Kim" />
              <Avatar.Root alt="Mike Park" />
          </HStack>
      );
  }

  ```
</Demo>

### Custom Fallback

FallbackPrimitive에 children을 전달하여 커스텀 fallback 콘텐츠를 표시합니다.

<Demo name="avatar/avatar-custom-fallback">
  ```tsx
  import { Avatar, HStack, Text, VStack } from '@vapor-ui/core';

  export default function AvatarCustomFallback() {
      return (
          <VStack $css={{ gap: '$150' }}>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-28" typography="body3" foreground="hint-100">
                      auto initial
                  </Text>
                  <Avatar.Root alt="John Doe">
                      <Avatar.FallbackPrimitive />
                  </Avatar.Root>
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-28" typography="body3" foreground="hint-100">
                      custom text
                  </Text>
                  <Avatar.Root alt="John Doe">
                      <Avatar.FallbackPrimitive>JD</Avatar.FallbackPrimitive>
                  </Avatar.Root>
              </HStack>
          </VStack>
      );
  }

  ```
</Demo>

### Custom Image

`children`으로 `Avatar.ImagePrimitive`와 `Avatar.FallbackPrimitive`를 전달하면 각 슬롯에 직접 props를 적용할 수 있습니다. `src`, `alt`, `crossOrigin` 등 이미지 관련 props는 `Avatar.Root`에 전달하면 내부 Primitive로 자동 전달됩니다.

<Demo name="avatar/avatar-custom-image">
  ```tsx
  import { Avatar, HStack, Text, VStack } from '@vapor-ui/core';

  const IMAGE_URL = 'https://avatars.githubusercontent.com/u/217160984?v=4';

  export default function AvatarCustomImage() {
      return (
          <VStack $css={{ gap: '$150' }}>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-40" typography="body3" foreground="hint-100">
                      ImagePrimitive
                  </Text>
                  <Avatar.Root src={IMAGE_URL} alt="User" crossOrigin="anonymous">
                      <Avatar.ImagePrimitive className="my-image" />
                      <Avatar.FallbackPrimitive />
                  </Avatar.Root>
              </HStack>
              <HStack $css={{ gap: '$150', alignItems: 'center' }}>
                  <Text className="w-40" typography="body3" foreground="hint-100">
                      FallbackPrimitive
                  </Text>
                  <Avatar.Root alt="User">
                      <Avatar.ImagePrimitive />
                      <Avatar.FallbackPrimitive>JD</Avatar.FallbackPrimitive>
                  </Avatar.Root>
              </HStack>
          </VStack>
      );
  }

  ```
</Demo>

## Props Table

***

### Avatar.Root

| Prop                    | Type                                                                                        | Default  | Description                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `shape`                 | `circle`, `square`                                                                          | `square` | 아바타 테두리 반경의 모양을 지정합니다. 기본값: `'square'`                                                                              |
| `size`                  | `sm`, `md`, `lg`, `xl`                                                                      | `md`     | 아바타의 크기를 지정합니다. 너비, 높이, 테두리 반경을 설정합니다. 기본값: `'md'`<br />폴백 콘텐츠의 크기를 지정합니다. 폰트 크기, 행간, 폰트 굵기, 자간을 설정합니다. 기본값: `'md'` |
| `onLoadingStatusChange` | `(status: ImageLoadingStatus) => void`                                                      | -        | 로딩 상태가 변경될 때 호출되는 콜백입니다.                                                                                            |
| `className`             | `string \| ((state: Avatar.Root.State) => (string \| undefined))`                           | -        | 요소에 적용할 CSS 클래스를 지정합니다. 컴포넌트의 상태를 기반으로 클래스를 반환하는 함수도 사용할 수 있습니다.                                                    |
| `fallbackElement`       | `ReactElement<AvatarFallbackPrimitive.Props, string \| JSXElementConstructor<any>>`         | -        |                                                                                                                     |
| `imageElement`          | `ReactElement<AvatarImagePrimitive.Props, string \| JSXElementConstructor<any>>`            | -        |                                                                                                                     |
| `delay`                 | `number`                                                                                    | -        | 폴백을 표시하기 전 대기 시간을 밀리초 단위로 지정합니다.                                                                                    |
| `style`                 | `React.CSSProperties \| ((state: Avatar.Root.State) => (React.CSSProperties \| undefined))` | -        | 요소에 적용할 스타일을 지정합니다. 컴포넌트의 상태를 기반으로 스타일 객체를 반환하는 함수도 사용할 수 있습니다.                                                     |
| `render`                | `ReactElement \| ((props: HTMLProps, state: Avatar.Root.State) => ReactElement)`            | -        | 컴포넌트의 HTML 요소를 다른 태그로 교체하거나 다른 컴포넌트와 합성할 때 사용합니다.<br /><br />`ReactElement` 또는 렌더링할 요소를 반환하는 함수를 전달할 수 있습니다.        |

#### Avatar.ImagePrimitive

| Prop        | Type                                                                                                  | Default | Description                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `className` | `string \| ((state: Avatar.ImagePrimitive.State) => (string \| undefined))`                           | -       | 요소에 적용할 CSS 클래스를 지정합니다. 컴포넌트의 상태를 기반으로 클래스를 반환하는 함수도 사용할 수 있습니다.                                             |
| `style`     | `React.CSSProperties \| ((state: Avatar.ImagePrimitive.State) => (React.CSSProperties \| undefined))` | -       | 요소에 적용할 스타일을 지정합니다. 컴포넌트의 상태를 기반으로 스타일 객체를 반환하는 함수도 사용할 수 있습니다.                                              |
| `render`    | `ReactElement \| ((props: HTMLProps, state: Avatar.ImagePrimitive.State) => ReactElement)`            | -       | 컴포넌트의 HTML 요소를 다른 태그로 교체하거나 다른 컴포넌트와 합성할 때 사용합니다.<br /><br />`ReactElement` 또는 렌더링할 요소를 반환하는 함수를 전달할 수 있습니다. |

#### Avatar.FallbackPrimitive

| Prop        | Type                                                                                                     | Default | Description                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `className` | `string \| ((state: Avatar.FallbackPrimitive.State) => (string \| undefined))`                           | -       | 요소에 적용할 CSS 클래스를 지정합니다. 컴포넌트의 상태를 기반으로 클래스를 반환하는 함수도 사용할 수 있습니다.                                             |
| `style`     | `React.CSSProperties \| ((state: Avatar.FallbackPrimitive.State) => (React.CSSProperties \| undefined))` | -       | 요소에 적용할 스타일을 지정합니다. 컴포넌트의 상태를 기반으로 스타일 객체를 반환하는 함수도 사용할 수 있습니다.                                              |
| `render`    | `ReactElement \| ((props: HTMLProps, state: Avatar.FallbackPrimitive.State) => ReactElement)`            | -       | 컴포넌트의 HTML 요소를 다른 태그로 교체하거나 다른 컴포넌트와 합성할 때 사용합니다.<br /><br />`ReactElement` 또는 렌더링할 요소를 반환하는 함수를 전달할 수 있습니다. |