Avatar

new

Anime PFP? We don't judge.

Demo
ALKP

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.

Fallback
KPGH

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.

Group
ALMCGHAE+3
ALMCGHAE+3

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.

With Image
Katherine Johnson
Albert Einstein

API Reference

Every part takes a class that merges with its own.

Data attributes

data-slotAttributesDescription
avatardata-sizeThe root, a span that clips to a circle.
avatar-imageThe img. Hidden with display: none until it has loaded.
avatar-fallbackThe fallback, rendered while the image has not loaded.
avatar-groupThe row.
avatar-group-countdata-sizeThe count, a circle like a fallback.

CSS variables

VariableDefaultDescription
--avatar-size2.5rem for mdWidth and height of an avatar or a count, set by size. A group overlaps its children by a quarter of it.
--avatar-ringvar(--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)]".

Changelog

  1. registry 0.22.0

    d4674af — AvatarFallback :delay-ms="0" shows the fallback once the image fails, like leaving delayMs out; Reka's fallback treated 0 as a delay that never started, so the avatar stayed blank.

  2. registry 0.6.0

    aa71d8d — Avatar: Avatar, AvatarImage, AvatarFallback, AvatarGroup and AvatarGroupCount. Five sizes from 24 to 64px; a group overlaps its members by a quarter of their size and rings them in --avatar-ring; Image goes in an avatar in place of AvatarImage for sources and layers.