---
title: "Avatar"
description: "An image element with a fallback for representing the user."
canonical_url: "https://vinicunca.dev/akar/components/avatar"
---
# Avatar

> An image element with a fallback for representing the user.

```vue [index.vue]
<script setup lang="ts">
import { AvatarFallback, AvatarImage, AvatarRoot } from 'akar'
import './styles.css'
</script>

<template>
  <div class="akar-demo akar-demo-Avatar">
    <div :style="{ display: 'flex', gap: '20px' }">
        <AvatarRoot class="AvatarRoot">
          <AvatarImage
            class="AvatarImage"
            src="https://images.unsplash.com/photo-1492633423870-43d1cd2775eb?&w=128&h=128&dpr=2&q=80"
            alt="Colm Tuite"
          />
          <AvatarFallback
            class="AvatarFallback"
            :delay-ms="600"
          >
            CT
          </AvatarFallback>
        </AvatarRoot>
        <AvatarRoot class="AvatarRoot">
          <AvatarImage
            class="AvatarImage"
            src="https://images.unsplash.com/photo-1511485977113-f34c92461ad9?ixlib=rb-1.2.1&w=128&h=128&dpr=2&q=80"
            alt="Pedro Duarte"
          />
          <AvatarFallback
            class="AvatarFallback"
            :delay-ms="600"
          >
            JD
          </AvatarFallback>
        </AvatarRoot>
        <AvatarRoot class="AvatarRoot">
          <AvatarFallback class="AvatarFallback">
            PD
          </AvatarFallback>
        </AvatarRoot>
      </div>
  </div>
</template>
```

```css [styles.css]
@import '../_colors/black-alpha.css';
@import '../_colors/grass.css';

@scope (.akar-demo-Avatar) {
.AvatarRoot {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  vertical-align: middle;
  overflow: hidden;
  user-select: none;
  width: 45px;
  height: 45px;
  border-radius: 100%;
  background-color: var(--black-a3);
}

.AvatarImage {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: inherit;
}

.AvatarFallback {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: white;
  color: var(--grass-11);
  font-size: 15px;
  line-height: 1;
  font-weight: 500;
}
}
```

## Features

- Automatic and manual control over when the image renders.
- Fallback part accepts any children.
- Optionally delay fallback rendering to avoid content flashing.

## Installation

Install the component from your command line.

```bash [pnpm]
pnpm add akar
```

```bash [yarn]
yarn add akar
```

```bash [npm]
npm install akar
```

```bash [bun]
bun add akar
```

## Anatomy

Import all parts and piece them together.

```vue
<script setup>
import { AvatarImage, AvatarRoot } from 'akar';
</script>

<template>
  <AvatarRoot>
    <AvatarImage />
    <AvatarFallback />
  </AvatarRoot>
</template>
```

## API Reference

### Root

Contains all the parts of an avatar

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"span"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |

[AvatarRoot.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Avatar/AvatarRoot.vue)

### Image

The image to render. By default it will only render when it has loaded. You can use the `@loadingStatusChange` handler if you need more control.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"img"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `crossOrigin` |  | `"" \| "anonymous" \| "use-credentials"` |  |
| `referrerPolicy` |  | `"" \| "no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` |  |
| `src*` |  | `string` |  |

**Events**

| Event | Payload | Description |
| --- | --- | --- |
| `loadingStatusChange` | `value: ImageLoadingStatus` | A callback providing information about the loading status of the image.<br><br>This is useful in case you want to control more precisely what to render as the image is loading. |

[AvatarImage.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Avatar/AvatarImage.vue)

### Fallback

An element that renders when the image hasn't loaded. This means whilst it's loading, or if there was an error. If you notice a flash during loading, you can provide a `delayMs` prop to delay its rendering so it only renders for those with slower connections. For more control, use the `@loadingStatusChange` emit on `AvatarImage`.

**Props**

| Prop | Default | Type | Description |
| --- | --- | --- | --- |
| `as` | `"span"` | `AsTag \| Component` | The element or component this component should render as. Can be overwritten by `asChild`. |
| `asChild` |  | `boolean` | Change the default rendered element for the one passed as a child, merging their props and behavior.<br><br>Read our [Composition](https://vinicunca.dev/akar/guides/composition) guide for more details. |
| `delayMs` |  | `number` | Useful for delaying rendering so it only appears for those with slower connections. |

[AvatarFallback.vue source](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Avatar/AvatarFallback.vue)

## Examples

### Clickable Avatar with tooltip

You can compose the Avatar with a [Tooltip](https://vinicunca.dev/akar/components/tooltip) to display extra information.

```vue
<script setup>
import { AvatarImage, AvatarRoot, TooltipArrow, TooltipRoot, TooltipTrigger } from 'akar'
</script>

<template>
  <TooltipRoot>
    <TooltipTrigger>
      <AvatarRoot>…</AvatarRoot>
    </TooltipTrigger>

    <TooltipContent side="top">
      Tooltip content
      <TooltipArrow />
    </TooltipContent>
  </TooltipRoot>
</template>
```

---

- [GitHub](https://github.com/vinicunca/akar/blob/v2.0.20/packages/core/src/Avatar)
- [npm](https://www.npmjs.com/package/akar)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.