Avatar
newAnime PFP? We don't judge.
Open Props in the corner of the example to try size.
size goes from xs (24px) to xl (64px), md by default. The fallback's text and icons scale with it.
Installation
Usage
<script setup lang="ts">
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
</script>
<template>
<Avatar>
<AvatarImage src="/me.jpg" alt="Kappa Person" />
<AvatarFallback>KP</AvatarFallback>
</Avatar>
</template>
The photo shows once it has loaded. Until then, or for good if it fails, AvatarFallback shows instead. Put initials or an icon in it, and they're sized for you.
Examples
Fallback
The fallback shows right away, so a slow photo shows initials first. Photos usually load fast? delay-ms holds the initials back, so they don't flash.
Square avatar? Add class="rounded-lg" to Avatar.
Group
AvatarGroup overlaps the avatars with a thin ring between them, and AvatarGroupCount is the "+3" circle at the end. The ring matches the page background; on another surface, set --avatar-ring to match it.
With Image
Need srcset, <picture> sources or a loading layer? Put an Image in the avatar instead of AvatarImage. Its ImageError becomes the fallback, so skip AvatarFallback.
Don't nest one inside the other: AvatarImage would hide Image until its own request finishes.

API Reference
Every part takes a class that merges with its own.
Avatar
| Prop | Default | Type and description |
|---|---|---|
| size | "md" | AvatarSizeWidth and height, 24px for |
| asChild | — | booleanRender the single child instead of a wrapper, merging the avatar's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A span by default. |
| Slot | Scope and description |
|---|---|
| default | {}An |
AvatarImage
| Prop | Default | Type and description |
|---|---|---|
| src* | — | stringThe image URL. The element stays hidden until it has loaded. |
| referrerPolicy | — | HTMLAttributeReferrerPolicyThe referrer sent with the request, as on |
| crossOrigin | — | "" | "anonymous" | "use-credentials"Requests the image with CORS, as on |
| asChild | — | booleanRender the single child instead of an img, merging the attributes onto it. |
| as | — | AsTag | ComponentThe element or component to render. An img by default. |
| Event | Payload and description |
|---|---|
| loadingStatusChange | [value: ImageLoadingStatus]Fires with |
AvatarFallback
| Prop | Default | Type and description |
|---|---|---|
| delayMs | — | numberMilliseconds to wait before rendering, so a photo that arrives quickly never shows the fallback first. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the fallback's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. A span by default. |
| Slot | Scope and description |
|---|---|
| default | {}Initials or an icon. |
AvatarGroup
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| as | "div" | AsTag | ComponentThe element or component to render. A div by default. |
| Slot | Scope and description |
|---|---|
| default | {}Avatars, and an |
AvatarGroupCount
| Prop | Default | Type and description |
|---|---|---|
| size | "md" | AvatarSizeThe same sizes as |
| asChild | — | booleanRender the single child instead of a wrapper, merging the count's attributes and classes onto it. |
| as | "span" | AsTag | ComponentThe element or component to render. A span by default. |
| Slot | Scope and description |
|---|---|
| default | {}The count, such as |
Props
- size
"md" AvatarSizeWidth and height, 24px forxsto 64px forxl, with the text and icon size of the fallback.md(40px) by default.- asChild
booleanRender the single child instead of a wrapper, merging the avatar's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A span by default.
Slots
- default
{}AnAvatarImageand anAvatarFallback, or anImage.
Props
- src*
stringThe image URL. The element stays hidden until it has loaded.- referrerPolicy
HTMLAttributeReferrerPolicyThe referrer sent with the request, as on<img>.- crossOrigin
"" | "anonymous" | "use-credentials"Requests the image with CORS, as on<img>.- asChild
booleanRender the single child instead of an img, merging the attributes onto it.- as
AsTag | ComponentThe element or component to render. An img by default.
Emits
- loadingStatusChange
[value: ImageLoadingStatus]Fires withidle,loading,loadedorerroras the load progresses.
Props
- delayMs
numberMilliseconds to wait before rendering, so a photo that arrives quickly never shows the fallback first.- asChild
booleanRender the single child instead of a wrapper, merging the fallback's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render. A span by default.
Slots
- default
{}Initials or an icon.
Props
- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- as
"div" AsTag | ComponentThe element or component to render. A div by default.
Slots
- default
{}Avatars, and anAvatarGroupCountlast.
Props
- size
"md" AvatarSizeThe same sizes asAvatar, so the count lines up with the avatars beside it.mdby default.- asChild
booleanRender the single child instead of a wrapper, merging the count's attributes and classes onto it.- as
"span" AsTag | ComponentThe element or component to render. A span by default.
Slots
- default
{}The count, such as+3, or an icon.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| avatar | data-size | The root, a span that clips to a circle. |
| avatar-image | The img. Hidden with display: none until it has loaded. | |
| avatar-fallback | The fallback, rendered while the image has not loaded. | |
| avatar-group | The row. | |
| avatar-group-count | data-size | The count, a circle like a fallback. |
CSS variables
| Variable | Default | Description |
|---|---|---|
| --avatar-size | 2.5rem for md | Width and height of an avatar or a count, set by size. A group overlaps its children by a quarter of it. |
| --avatar-ring | var(--color-background) | Colour of the 2px ring between the members of a group. Set it on the group to the surface it sits on, for example class="[--avatar-ring:--theme(--color-card)]". |