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

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

***

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

<Demo name="avatar/default-avatar">
  ```json doc-gen:file
  {
      "file": "./src/components/demo/examples/avatar/default-avatar.tsx",
      "codeblock": true
  }
  ```
</Demo>

## Property

***

### Size

Avatar 사이즈는 sm, md, lg, xl 로 제공합니다.

<Demo name="avatar/avatar-size">
  ```json doc-gen:file
  {
      "file": "./src/components/demo/examples/avatar/avatar-size.tsx",
      "codeblock": true
  }
  ```
</Demo>

### Shape

Avatar 모양은 circle, square 로 제공합니다.

<Demo name="avatar/avatar-shape">
  ```json doc-gen:file
  {
      "file": "./src/components/demo/examples/avatar/avatar-shape.tsx",
      "codeblock": true
  }
  ```
</Demo>

## Examples

***

### Custom Usage

Avatar의 유연한 사용 예시입니다.

<Demo name="avatar/flexible">
  ```json doc-gen:file
  {
      "file": "./src/components/demo/examples/avatar/flexible.tsx",
      "codeblock": true
  }
  ```
</Demo>

### Fallback Only

이미지 로드 실패 시 표시되는 Fallback 텍스트나 이니셜을 사용하는 패턴입니다.

<Demo name="avatar/avatar-fallback-only">
  ```json doc-gen:file
  {
      "file": "./src/components/demo/examples/avatar/avatar-fallback-only.tsx",
      "codeblock": true
  }
  ```
</Demo>

## Props Table

***

### Avatar.Root

Avatar의 메인 컨테이너 컴포넌트입니다. size와 shape 속성을 제공하며, 모든 하위 컴포넌트에서 공통으로 사용할 수 있도록 컨텍스트를 제공합니다.

| prop        | type                    | default  | description                                                        |
| ----------- | ----------------------- | -------- | ------------------------------------------------------------------ |
| `render`    | `ReactElement,function` | `span`   | 아바타를 렌더링할 때 사용할 커스텀 렌더링 요소입니다.                                     |
| `size`      | `sm,md,lg,xl`           | `md`     | 아바타 컴포넌트의 크기를 조절합니다.                                               |
| `shape`     | `circle,square`         | `square` | 아바타 컴포넌트의 모양을 조절합니다.                                               |
| `alt`       | `string`                | `-`      | 웹 접근성을 위한 아바타 이미지의 대체 텍스트입니다.                                      |
| `src`       | `string`                | `-`      | 아바타 이미지의 소스 URL입니다.                                                |
| `delay`     | `number`                | `null`   | 폴백을 표시하기 전의 지연 시간(밀리초)입니다.                                         |
| `children`  | `ReactNode`             | `null`   | 자식 컴포넌트(Avatar.Image, Avatar.Fallback)입니다.                         |
| `className` | `string,function`       | `null`   | 아바타의 최상위 요소에 적용할 CSS 클래스명입니다. 함수 형태로 전달하면 상태에 따른 동적 클래스 적용이 가능합니다. |

### Avatar.ImagePrimitive

Avatar 이미지를 표시하는 컴포넌트입니다. src가 로드되지 않거나 오류가 발생할 경우 자동으로 Fallback 컴포넌트가 표시됩니다.

| prop                    | type                    | default | description                                                                             |
| ----------------------- | ----------------------- | ------- | --------------------------------------------------------------------------------------- |
| `render`                | `ReactElement,function` | `img`   | 이미지를 렌더링할 때 사용할 커스텀 렌더링 요소입니다.                                                          |
| `src`                   | `string`                | `-`     | 표시할 이미지의 소스 URL입니다. Root에서 상속받습니다.                                                      |
| `alt`                   | `string`                | `-`     | 이미지의 대체 텍스트입니다. Root에서 상속받습니다.                                                          |
| `onLoadingStatusChange` | `function`              | `-`     | 이미지 로딩 상태 변경 시 호출되는 콜백 함수입니다. (status: 'loading' \| 'loaded' \| 'error') => void 형태입니다. |
| `className`             | `string,function`       | `-`     | 이미지에 적용할 CSS 클래스입니다. 함수 형태로 전달하면 상태에 따른 동적 클래스 적용이 가능합니다.                               |

### Avatar.FallbackPrimitive

이미지가 로드되지 않을 때 표시되는 대체 컴포넌트입니다. alt 속성을 기반으로 자동으로 이니셜을 생성하고, Linear Congruential Generator 알고리즘을 사용해 일관된 배경 색상을 제공합니다.

| prop        | type                    | default | description                                              |
| ----------- | ----------------------- | ------- | -------------------------------------------------------- |
| `render`    | `ReactElement,function` | `span`  | 폴백 콘텐츠를 렌더링할 때 사용할 커스텀 렌더링 요소입니다.                        |
| `delay`     | `number`                | `-`     | 폴백을 표시하기 전의 지연 시간(밀리초)입니다. 느린 연결에서만 표시되도록 지연시키는데 유용합니다.  |
| `children`  | `ReactNode`             | `-`     | 이미지 로딩 실패 시 표시할 콘텐츠입니다. 기본적으로 alt에서 이니셜을 자동 생성합니다.       |
| `className` | `string,function`       | `-`     | 폴백에 적용할 CSS 클래스입니다. 함수 형태로 전달하면 상태에 따른 동적 클래스 적용이 가능합니다. |