---
title: Avatar
description: "`Avatar` is a component that displays a profile picture or an icon with initials representing a user."
links:
  - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/avatar/avatar.style.ts
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/avatar
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-avatar--basic
---

```tsx
<Avatar
  name="Hirotomo Yamada"
  src="https://avatars.githubusercontent.com/u/84060430?v=4"
/>
```

## Usage

```tsx
import { Avatar, AvatarGroup } from "@yamada-ui/react"
```

```tsx
import { Avatar, AvatarGroup } from "@/components/ui"
```

```tsx
import { Avatar, AvatarGroup } from "@workspaces/ui"
```

```tsx
<Avatar />
```

```tsx
<AvatarGroup.Root>
  <AvatarGroup.Item />
</AvatarGroup.Root>
```

### Change Variant

```tsx
<Wrap gap="md">
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant, key) => (
      <Avatar variant={variant} name="Hirotomo Yamada" key={key} />
    )}
  </For>
</Wrap>
```

### Change Size

```tsx
<Wrap gap="md">
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size, key) => <Avatar size={size} name="Hirotomo Yamada" key={key} />}
  </For>
</Wrap>
```

### Change Shape

```tsx
<Wrap gap="md">
  <For each={["circle", "square", "rounded"]}>
    {(size, key) => <Avatar shape={size} name="Hirotomo Yamada" key={key} />}
  </For>
</Wrap>
```

### Display Initials

When you set a string to name, an icon with the user's initials will be displayed.

```tsx
<Avatar name="Hirotomo Yamada" />
```

### Display an Image

If you want to display an image in the avatar, set the path to `src`.

```tsx
<Avatar src="https://avatars.githubusercontent.com/u/84060430?v=4" />
```

### Fallback

There are two fallbacks if the loading of `src` fails:

- If `name` is provided: It uses an icon with the user's initials
- If `name` is not provided: It uses the default avatar icon.

```tsx
<Wrap gap="md">
  <Avatar
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <Avatar name="Hirotomo Yamada" src="https://not-found.com" />
  <Avatar src="https://not-found.com" />
</Wrap>
```

### Customize the Fallback

Here is an example of customizing the fallback icon and background color.

```tsx
<Wrap gap="md">
  <Avatar bg="warning" src="https://not-found.com" />
  <Avatar icon={<GhostIcon />} src="https://not-found.com" />
</Wrap>
```

### Use random color

```tsx
const randomColorScheme = (name: string) => {
  const index = name.charCodeAt(0) % COLOR_SCHEMES.length
  return COLOR_SCHEMES[index]
}

return (
  <Wrap gap="md">
    <For each={["Hirotomo Yamada", "Koiso Kenji", "Shinohara Natsuki"]}>
      {(name, index) => (
        <Avatar key={index} name={name} colorScheme={randomColorScheme(name)} />
      )}
    </For>
  </Wrap>
)
```

### Grouping

If you want to control the number of avatars displayed, specify a number with `max`. If there are more avatars than the specified number, it truncates and displays the remaining avatars as `+X`.

```tsx
<AvatarGroup.Root max={3}>
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
  <AvatarGroup.Item
    name="Hirotomo Yamada"
    src="https://avatars.githubusercontent.com/u/84060430?v=4"
  />
</AvatarGroup.Root>
```

## Uses Components & Hooks

<Uses name="avatar" />

## Props

### Avatar

| Prop             | Default         | Type                                                                                                                      | Description                                                                                                                                                                                   |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`             | -               | `As`                                                                                                                      | The HTML element to render.                                                                                                                                                                   |
| `asChild`        | -               | `boolean`                                                                                                                 | Merges its props onto its immediate child.                                                                                                                                                    |
| `css`            | -               | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                                                                                                                                                                               |
| `colorScheme`    | -               | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                                                                                                                                                                   |
| `size`           | `"md"`          | `"lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                    | The size of the component.                                                                                                                                                                    |
| `variant`        | `"solid"`       | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                           | The variant of the component.                                                                                                                                                                 |
| `alt`            | -               | `HTMLProps<"img">["alt"]`                                                                                                 | The `HTMLImageElement` property `alt`.                                                                                                                                                        |
| `crossOrigin`    | -               | `HTMLProps<"img">["crossOrigin"]`                                                                                         | The `HTMLImageElement` property `crossOrigin`.                                                                                                                                                |
| `fallback`       | -               | `ReactNode`                                                                                                               | The fallback text to display if the image is not provided.                                                                                                                                    |
| `fallbackProps`  | -               | `AvatarFallbackProps`                                                                                                     | The props to pass to the fallback component.                                                                                                                                                  |
| `format`         | -               | `(name: string) => string`                                                                                                | Function to get the initials to display.                                                                                                                                                      |
| `icon`           | -               | `ReactElement`                                                                                                            | The avatar icon to use.                                                                                                                                                                       |
| `imageProps`     | -               | `AvatarImageProps`                                                                                                        | The props to pass to the image component.                                                                                                                                                     |
| `loading`        | -               | `HTMLProps<"img">["loading"]`                                                                                             | Defines loading strategy.                                                                                                                                                                     |
| `name`           | -               | `string`                                                                                                                  | The name of the person in the avatar. - If `src` has loaded, the name will be used as the `alt` attribute of the `img` - If `src` is not loaded, the name will be used to create the initials |
| `referrerPolicy` | `"no-referrer"` | `HTMLProps<"img">["referrerPolicy"]`                                                                                      | Defining which referrer is sent when fetching the resource.                                                                                                                                   |
| `src`            | -               | `HTMLProps<"img">["src"]`                                                                                                 | The image url of the avatar.                                                                                                                                                                  |
| `srcSet`         | -               | `HTMLProps<"img">["srcSet"]`                                                                                              | List of sources to use for different screen resolutions.                                                                                                                                      |

### AvatarGroup.Root

| Prop          | Default   | Type                                                                                                                      | Description                                  |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `as`          | -         | `As`                                                                                                                      | The HTML element to render.                  |
| `asChild`     | -         | `boolean`                                                                                                                 | Merges its props onto its immediate child.   |
| `css`         | -         | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                              |
| `colorScheme` | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                  |
| `size`        | `"md"`    | `"lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                    | The size of the component.                   |
| `variant`     | `"solid"` | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                           | The variant of the component.                |
| `max`         | -         | `number`                                                                                                                  | The maximum number of visible avatars.       |
| `reverse`     | -         | `boolean`                                                                                                                 | Whether to reverse the order of the avatars. |

### AvatarGroup.Item

| Prop             | Default         | Type                                                                                                                      | Description                                                                                                                                                                                   |
| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`             | -               | `As`                                                                                                                      | The HTML element to render.                                                                                                                                                                   |
| `asChild`        | -               | `boolean`                                                                                                                 | Merges its props onto its immediate child.                                                                                                                                                    |
| `css`            | -               | `CSSObject \| CSSObject[]`                                                                                                | The CSS object.                                                                                                                                                                               |
| `colorScheme`    | -               | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...` | Set color scheme variables.                                                                                                                                                                   |
| `size`           | `"md"`          | `"lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                    | The size of the component.                                                                                                                                                                    |
| `variant`        | `"solid"`       | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                           | The variant of the component.                                                                                                                                                                 |
| `alt`            | -               | `HTMLProps<"img">["alt"]`                                                                                                 | The `HTMLImageElement` property `alt`.                                                                                                                                                        |
| `crossOrigin`    | -               | `HTMLProps<"img">["crossOrigin"]`                                                                                         | The `HTMLImageElement` property `crossOrigin`.                                                                                                                                                |
| `fallback`       | -               | `ReactNode`                                                                                                               | The fallback text to display if the image is not provided.                                                                                                                                    |
| `fallbackProps`  | -               | `AvatarFallbackProps`                                                                                                     | The props to pass to the fallback component.                                                                                                                                                  |
| `format`         | -               | `(name: string) => string`                                                                                                | Function to get the initials to display.                                                                                                                                                      |
| `icon`           | -               | `ReactElement`                                                                                                            | The avatar icon to use.                                                                                                                                                                       |
| `imageProps`     | -               | `AvatarImageProps`                                                                                                        | The props to pass to the image component.                                                                                                                                                     |
| `loading`        | -               | `HTMLProps<"img">["loading"]`                                                                                             | Defines loading strategy.                                                                                                                                                                     |
| `name`           | -               | `string`                                                                                                                  | The name of the person in the avatar. - If `src` has loaded, the name will be used as the `alt` attribute of the `img` - If `src` is not loaded, the name will be used to create the initials |
| `referrerPolicy` | `"no-referrer"` | `HTMLProps<"img">["referrerPolicy"]`                                                                                      | Defining which referrer is sent when fetching the resource.                                                                                                                                   |
| `src`            | -               | `HTMLProps<"img">["src"]`                                                                                                 | The image url of the avatar.                                                                                                                                                                  |
| `srcSet`         | -               | `HTMLProps<"img">["srcSet"]`                                                                                              | List of sources to use for different screen resolutions.                                                                                                                                      |

## Accessibility

### ARIA Roles and Attributes

| Component          | Roles and Attributes | Usage                                                                                                                                                                            |
| ------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AvatarImage`      | `alt`                | Alternative text for the avatar image. The component uses the `name` prop as the value for the `alt` attribute; if `name` is not provided, it uses the `alt` prop value instead. |
| `AvatarFallback`   | `role="img"`         | Indicates that this is an image.                                                                                                                                                 |
|                    | `aria-label`         | This is set when `fallback` is not provided. Sets the value of `name` or `alt` if provided. Otherwise, sets `"Avatar Icon"`.                                                     |
| `AvatarGroup.Root` | `role="group"`       | Indicates that it is a group.                                                                                                                                                    |