Avatar

An image element with a text fallback for representing a user or entity.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/avatar.json

Usage

import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar"
import { AvatarGroup } from "@/components/ui/avatar-group"

Examples

Default

Image with a text fallback, plus an optional status dot.

MDUI
SCOnline

Sizes

Five sizes from one prop. The fallback text scales with the box.

MDMDMDMDMD

Group

A row of overlapping people, such as a team or the people on a document. Each avatar is ringed in the colour of the surface behind it, so the row works on the page and on a card. max folds the rest into a +N chip. Point at one to lift it; the row springs back when the pointer leaves.

MDSCPNSO3 more

When each person opens their profile, wrap each Avatar in a bare Button with a round focus ring. Keyboard focus lifts the avatar the same way the pointer does.

API Reference

PropTypeDefaultDescription
sizeAvatar"xs" | "sm" | "default" | "lg" | "xl""default"The avatar size: xs (20px, beside 14px text), sm (24px), default (32px), lg (40px), or xl (48px). The fallback text scales with it, so you never set two classes.
srcAvatarImagestringNoneImage source URL. The image only renders once it has loaded; the fallback shows until then.
onLoadingStatusChangeAvatarImage(status: "idle" | "loading" | "loaded" | "error") => voidNoneCalled when the image's loading status changes.
delayMsAvatarFallbacknumberNoneDelay in milliseconds before the fallback renders, avoiding a flash when the image loads quickly.
sizeAvatarGroup"xs" | "sm" | "default" | "lg" | "xl""default"Every avatar in the row takes this size, and the overlap (about a fifth of the avatar: 4, 4, 6, 8 and 10px), ring and lift scale with it. An Avatar's own size still wins.
maxAvatarGroupnumberNoneShow at most this many avatars. The rest fold into a +N chip at the end, read aloud as "N more".
aria-labelAvatarGroupstringNoneNames the group for screen readers: who these people are ("Team", "People on this call").
sizeAvatar"xs" | "sm" | "default" | "lg" | "xl" = "default"The avatar size: xs (20px, beside 14px text), sm (24px), default (32px), lg (40px), or xl (48px). The fallback text scales with it, so you never set two classes.
srcAvatarImagestringImage source URL. The image only renders once it has loaded; the fallback shows until then.
onLoadingStatusChangeAvatarImage(status: "idle" | "loading" | "loaded" | "error") => voidCalled when the image's loading status changes.
delayMsAvatarFallbacknumberDelay in milliseconds before the fallback renders, avoiding a flash when the image loads quickly.
sizeAvatarGroup"xs" | "sm" | "default" | "lg" | "xl" = "default"Every avatar in the row takes this size, and the overlap (about a fifth of the avatar: 4, 4, 6, 8 and 10px), ring and lift scale with it. An Avatar's own size still wins.
maxAvatarGroupnumberShow at most this many avatars. The rest fold into a +N chip at the end, read aloud as "N more".
aria-labelAvatarGroupstringNames the group for screen readers: who these people are ("Team", "People on this call").