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

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

<Demo file="components/(components)/avatar/demos/default-avatar.tsx" />

## Property

***

### Shape

Avatar의 모양을 설정합니다.

<Demo file="components/(components)/avatar/demos/avatar-shape.tsx" />

### Size

Avatar의 크기를 설정합니다.

<Demo file="components/(components)/avatar/demos/avatar-size.tsx" />

## Examples

***

### Fallback

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

<Demo file="components/(components)/avatar/demos/avatar-fallback.tsx" />

### Custom Fallback

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

<Demo file="components/(components)/avatar/demos/avatar-custom-fallback.tsx" />

### Custom Image

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

<Demo file="components/(components)/avatar/demos/avatar-custom-image.tsx" />

## Props Table

***

### Avatar.Root

| Prop                    | Type                                          | Default  | Description                                                                                                                                                                                               |
| ----------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shape`                 | `circle`, `square`                            | `square` | Corner style of the avatar.                                                                                                                                                                               |
| `size`                  | `sm`, `md`, `lg`, `xl`                        | `md`     | Size of the avatar, controlling width, height, corner radius, and the typography of the fallback.                                                                                                         |
| `onLoadingStatusChange` | `function`                                    | -        | Callback fired when the loading status changes.                                                                                                                                                           |
| `className`             | `string`, `function`                          | -        | CSS class applied to the element, or a function that<br />returns a class based on the component's state.                                                                                                 |
| `fallbackElement`       | `ReactElement<AvatarFallbackPrimitive.Props>` | -        | Replaces the default `Avatar.FallbackPrimitive`. Ignored when `children` are given.                                                                                                                       |
| `imageElement`          | `ReactElement<AvatarImagePrimitive.Props>`    | -        | Replaces the default `Avatar.ImagePrimitive`. Ignored when `children` are given.                                                                                                                          |
| `style`                 | `React.CSSProperties`, `function`             | -        | Style applied to the element, or a function that<br />returns a style object based on the component's state.                                                                                              |
| `delay`                 | `number`                                      | `0`      | How long to wait before showing the fallback. Specified in milliseconds.                                                                                                                                  |
| `keepMounted`           | `boolean`                                     | `false`  | Whether the image element stays mounted and loads in place instead of being preloaded.<br />Supports `loading="lazy"` and optimized image components such as `next/image`.                                |
| `render`                | `ReactElement`, `function`                    | -        | 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. |

#### Avatar.ImagePrimitive

| Prop        | Type                              | Default | Description                                                                                                                                                                                               |
| ----------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string`, `function`              | -       | CSS class applied to the element, or a function that<br />returns a class based on the component's state.                                                                                                 |
| `style`     | `React.CSSProperties`, `function` | -       | Style applied to the element, or a function that<br />returns a style object based on the component's state.                                                                                              |
| `render`    | `ReactElement`, `function`        | -       | 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. |

#### Avatar.FallbackPrimitive

| Prop        | Type                              | Default | Description                                                                                                                                                                                               |
| ----------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `className` | `string`, `function`              | -       | CSS class applied to the element, or a function that<br />returns a class based on the component's state.                                                                                                 |
| `style`     | `React.CSSProperties`, `function` | -       | Style applied to the element, or a function that<br />returns a style object based on the component's state.                                                                                              |
| `render`    | `ReactElement`, `function`        | -       | 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. |