---
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

***

### Size

Avatar의 크기를 설정합니다.

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

### Shape

Avatar의 모양을 설정합니다.

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

## Examples

***

### Composition Pattern

Avatar 컴포넌트의 다양한 구성 패턴입니다.

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

### Fallback Only

이미지 없이 대체 텍스트만 표시합니다.

<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

| Prop        | Type                                                                                          | Default | Description                                                                                                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string`, `((state: Avatar.Root.State) => string)`, `undefined`                               | -       | CSS class applied to the element, or a function that<br />returns a class based on the component’s state.                                                                                                 |
| `render`    | `((props: HTMLProps, state: Avatar.Root.State) => ReactElement)`, `ReactElement`, `undefined` | -       | Allows you to replace the component’s HTML element<br />with a different tag, or compose it with another component.<br /><br />Accepts a `ReactElement` or a function that returns the element to render. |
| `src`       | `string`, `undefined`                                                                         | -       | 이미지 소스 URL                                                                                                                                                                                                |
| **alt**     | `string`                                                                                      | -       | 대체 텍스트, 폴백 이니셜 생성에도 사용                                                                                                                                                                                    |
| `delay`     | `number`, `undefined`                                                                         | -       | 폴백 표시 전 지연 시간 (밀리초)                                                                                                                                                                                       |

**Variants**

| Variant | Values                 | Default  |
| ------- | ---------------------- | -------- |
| `size`  | `sm`, `md`, `lg`, `xl` | `md`     |
| `shape` | `square`, `circle`     | `square` |

#### Avatar.ImagePrimitive

| Prop                    | Type                                                                                                    | Default | Description                                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className`             | `string`, `((state: Avatar.ImagePrimitive.State) => string)`, `undefined`                               | -       | CSS class applied to the element, or a function that<br />returns a class based on the component’s state.                                                                                                 |
| `render`                | `((props: HTMLProps, state: Avatar.ImagePrimitive.State) => ReactElement)`, `ReactElement`, `undefined` | -       | Allows you to replace the component’s HTML element<br />with a different tag, or compose it with another component.<br /><br />Accepts a `ReactElement` or a function that returns the element to render. |
| `onLoadingStatusChange` | `((status: ImageLoadingStatus) => void)`, `undefined`                                                   | -       | Callback fired when the loading status changes.                                                                                                                                                           |

#### Avatar.FallbackPrimitive

| Prop        | Type                                                                                                       | Default | Description                                                                                                                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string`, `((state: Avatar.FallbackPrimitive.State) => string)`, `undefined`                               | -       | CSS class applied to the element, or a function that<br />returns a class based on the component’s state.                                                                                                 |
| `render`    | `((props: HTMLProps, state: Avatar.FallbackPrimitive.State) => ReactElement)`, `ReactElement`, `undefined` | -       | Allows you to replace the component’s HTML element<br />with a different tag, or compose it with another component.<br /><br />Accepts a `ReactElement` or a function that returns the element to render. |