Avatar
An image element with a fallback for representing a user. Seven sizes, circle or square, with status badges and overlapping groups.
Playground
<Avatar>
<AvatarImage src="https://github.com/shadcn.png" alt="User" />
<AvatarFallback>C</AvatarFallback>
</Avatar>Preview
AvatarImage renders once the image loads; AvatarFallback shows initials until then (or forever, if there is no image). Add an AvatarBadge for a status dot.
<Avatar>
<AvatarImage src="https://github.com/shadcn.png" alt="User" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar>
<AvatarImage src="https://github.com/shadcn.png" alt="User" />
<AvatarFallback>CN</AvatarFallback>
<AvatarBadge />
</Avatar>Installation
npx shadcn@latest add https://espresso-base-ui.vercel.app/r/avatar.jsonUsage
import {
Avatar,
AvatarBadge,
AvatarFallback,
AvatarGroup,
AvatarGroupCount,
AvatarImage,
} from "@/components/ui/avatar"<Avatar size="lg">
<AvatarImage src="/avatars/user.png" alt="User" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>Sizes
size runs from xs (16px) to 3xl (46px). The fallback text, icon sizing, badge and group overlap all scale with it automatically.
<Avatar size="xs"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="sm"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="default"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="lg"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="xl"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="2xl"><AvatarFallback>CN</AvatarFallback></Avatar>
<Avatar size="3xl"><AvatarFallback>CN</AvatarFallback></Avatar>Square
variant="square" swaps the circle for a rounded square whose corner radius steps up with the size token.
<Avatar variant="square">
<AvatarImage src="https://github.com/shadcn.png" alt="User" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar variant="square" size="2xl">
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar variant="square" size="2xl">
<User className="text-muted-foreground" />
<AvatarBadge />
</Avatar>Icon
Pass an icon as a direct child of Avatar (or inside AvatarFallback) – the root centers it and sizes the svg per size token.
<Avatar size="lg">
<User className="text-muted-foreground" />
</Avatar>
<Avatar size="lg">
<AvatarFallback>
<User className="text-muted-foreground" />
</AvatarFallback>
</Avatar>Group
AvatarGroup overlaps its children by each size's --overlap amount, ringed in the background color and stacked first-on-top; close with an AvatarGroupCount for the overflow.
<AvatarGroup>
<Avatar size="xl">
<AvatarImage src="https://github.com/shadcn.png" alt="User" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
<Avatar size="xl">
<AvatarFallback>AB</AvatarFallback>
</Avatar>
<Avatar size="xl">
<User className="text-muted-foreground" />
</Avatar>
<AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>API reference
Built on the Base UI Avatar primitive – Avatar, AvatarImage and AvatarFallback forward all of their Base UI props (like AvatarImage's onLoadingStatusChange), and every part accepts className.
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "circle" | "square" | "circle" | Shape. square applies a per-size corner radius (rounded-2xs at xs up to rounded-lg at 3xl). |
| size | "xs" | "sm" | "default" | "lg" | "xl" | "2xl" | "3xl" | "default" | Diameter from 16px (xs) to 46px (3xl). Also scales fallback typography, icon size, badge size and group overlap. |
| Component | Description |
|---|---|
| AvatarImage | The user image (data-slot="avatar-image"). Object-cover, inherits the root radius; unmounts while loading or on error so the fallback shows. |
| AvatarFallback | Initials or icon shown when the image is unavailable (data-slot="avatar-fallback"). Text and svg sizes track the root size. |
| AvatarBadge | Status dot pinned to the bottom-right corner (data-slot="avatar-badge"). Green by default – recolor with className and drop in an icon at larger sizes. |
| AvatarGroup | Overlapping stack (data-slot="avatar-group"). Rings each avatar with the background color and z-stacks the first child on top. |
| AvatarGroupCount | Overflow counter styled like a fallback avatar (data-slot="avatar-group-count"). Matches the size of the avatars in the group. |
Styling hooks
The root exposes data-slot="avatar" plus data-size and data-variant, and each part has its own data-slot – the badge, fallback and group count all key their styles off these, and you can too. The avatarVariants cva helper is exported for building custom avatar-shaped surfaces:
import { avatarVariants } from "@/components/ui/avatar"
<span className={cn(avatarVariants({ variant: "square", size: "lg" }))}>
...
</span>