---
version: 1.0.0-beta.6
---
# 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

***

### Shape

Avatar의 모양을 설정합니다.

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

### Size

Avatar의 크기를 설정합니다.

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

## Examples

***

### Fallback

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

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

### Custom Fallback

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

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

## Anatomy

***

컴포넌트의 구조를 탐색하고 각 파트의 역할을 확인합니다. 파트 이름에 마우스를 올리면 해당 영역이 하이라이트됩니다.

<ComponentExplorer name="avatar/anatomy-avatar" componentName="avatar" />

## Props Table

***

### Avatar.Root

| Prop        | Type                                 | Default  | Description                                                                                    |
| ----------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------- |
| `size`      | `sm`, `md`, `lg`, `xl`               | `md`     | 아바타 크기                                                                                         |
| `className` | `string`, `(state: State) => string` | -        | 요소에 적용된 CSS 클래스 또는 컴포넌트의 상태에 따라 클래스를 반환하는 함수.                                                  |
| **alt**     | `string`                             | -        | 대체 텍스트, 폴백 이니셜 생성에도 사용                                                                         |
| `shape`     | `circle`, `square`                   | `square` | 아바타 모서리 형태                                                                                     |
| `src`       | `string`                             | -        | 이미지 소스 URL                                                                                     |
| `render`    | `ReactElement`                       | -        | 컴포넌트의 HTML 요소를 다른 태그로 대체하거나 다른 컴포넌트와 조합할 수 있습니다. 렌더링할 요소를 반환하는 `ReactElement` 또는 함수를 인수로 받습니다. |
| `delay`     | `number`                             | -        | 폴백 표시 전 지연 시간 (밀리초)                                                                            |

#### Avatar.ImagePrimitive

| Prop                    | Type                                   | Default | Description                                                                                    |
| ----------------------- | -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `className`             | `string`, `(state: State) => string`   | -       | 요소에 적용된 CSS 클래스 또는 컴포넌트의 상태에 따라 클래스를 반환하는 함수.                                                  |
| `render`                | `ReactElement`                         | -       | 컴포넌트의 HTML 요소를 다른 태그로 대체하거나 다른 컴포넌트와 조합할 수 있습니다. 렌더링할 요소를 반환하는 `ReactElement` 또는 함수를 인수로 받습니다. |
| `onLoadingStatusChange` | `(status: ImageLoadingStatus) => void` | -       | 로딩 상태가 변경될 때 호출되는 콜백                                                                           |

#### Avatar.FallbackPrimitive

| Prop        | Type                                 | Default | Description                                                                                    |
| ----------- | ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `className` | `string`, `(state: State) => string` | -       | 요소에 적용된 CSS 클래스 또는 컴포넌트의 상태에 따라 클래스를 반환하는 함수.                                                  |
| `render`    | `ReactElement`                       | -       | 컴포넌트의 HTML 요소를 다른 태그로 대체하거나 다른 컴포넌트와 조합할 수 있습니다. 렌더링할 요소를 반환하는 `ReactElement` 또는 함수를 인수로 받습니다. |
