Shadcn Avatar
Free shadcn/ui avatar component for React — a Radix image with a graceful initials fallback. Sizes, an avatar group/stack, status indicators, and square/ringed shapes. The examples official shadcn never shipped.
Installation
{
"registries": {
"@designrevision": "https://registry.designrevision.com/r/{name}.json"
}
}Add to your existing components.json. Requires shadcn/ui v2.3+.
Packages
Props
No props documented yet.
"use client"
import * as React from "react"
import * as AvatarPrimitive from "@radix-ui/react-avatar"
import { cn } from "@/lib/utils"
function Avatar({
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Root>) {
return (
<AvatarPrimitive.Root
data-slot="avatar"
className={cn(
"relative flex size-8 shrink-0 overflow-hidden rounded-full",
className
)}
{...props}
/>
)
}
function AvatarImage({
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
return (
<AvatarPrimitive.Image
data-slot="avatar-image"
className={cn("aspect-square size-full", className)}
{...props}
/>
)
}
function AvatarFallback({
className,
...props
}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
return (
<AvatarPrimitive.Fallback
data-slot="avatar-fallback"
className={cn(
"bg-muted flex size-full items-center justify-center rounded-full",
className
)}
{...props}
/>
)
}
export { Avatar, AvatarImage, AvatarFallback }
Examples
Avatar
The canonical avatar — an image with an initials fallback that shows while it loads or if it fails.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
export default function AvatarDemo01() {
return (
<Avatar>
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
)
}
Fallbacks
Initials fallbacks for when there is no image — plain and colored.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
const colored = [
{ initials: "AL", color: "bg-rose-500" },
{ initials: "BC", color: "bg-blue-500" },
{ initials: "CD", color: "bg-emerald-500" },
{ initials: "DE", color: "bg-violet-500" },
]
export default function AvatarFallbackDemo01() {
return (
<div className="flex items-center gap-3">
{/* Plain fallback (shows when there's no image). */}
<Avatar>
<AvatarFallback>JD</AvatarFallback>
</Avatar>
{/* Colored fallbacks. */}
{colored.map((person) => (
<Avatar key={person.initials}>
<AvatarFallback className={`${person.color} text-white`}>
{person.initials}
</AvatarFallback>
</Avatar>
))}
</div>
)
}
Sizes
Avatars from `size-6` to `size-16` — set the size with a className on `Avatar`.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
const sizes = ["size-6", "size-8", "size-10", "size-12", "size-16"]
export default function AvatarSizes01() {
return (
<div className="flex items-center gap-4">
{sizes.map((size) => (
<Avatar key={size} className={size}>
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
))}
</div>
)
}
Avatar group
A stacked group of overlapping avatars (`-space-x` + ring) with a "+N" overflow.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
const members = [
{ src: "https://github.com/shadcn.png", fallback: "CN" },
{ src: "https://github.com/leerob.png", fallback: "LR" },
{ src: "https://github.com/evilrabbit.png", fallback: "ER" },
{ src: "https://github.com/vercel.png", fallback: "VC" },
]
export default function AvatarGroup01() {
return (
<div className="flex -space-x-2">
{members.map((member, index) => (
<Avatar key={index} className="ring-background ring-2">
<AvatarImage src={member.src} alt="" />
<AvatarFallback>{member.fallback}</AvatarFallback>
</Avatar>
))}
<Avatar className="ring-background ring-2">
<AvatarFallback className="text-muted-foreground text-xs">
+3
</AvatarFallback>
</Avatar>
</div>
)
}
Status indicator
An online / away / offline status dot pinned to the bottom-right of the avatar.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
const people = [
{ src: "https://github.com/shadcn.png", fallback: "CN", status: "bg-green-500", label: "Online" },
{ src: "https://github.com/leerob.png", fallback: "LR", status: "bg-amber-500", label: "Away" },
{ src: "https://github.com/evilrabbit.png", fallback: "ER", status: "bg-muted-foreground", label: "Offline" },
]
export default function AvatarStatus01() {
return (
<div className="flex items-center gap-6">
{people.map((person, index) => (
<div key={index} className="relative">
<Avatar className="size-10">
<AvatarImage src={person.src} alt="" />
<AvatarFallback>{person.fallback}</AvatarFallback>
</Avatar>
<span
title={person.label}
className={`ring-background absolute right-0 bottom-0 size-3 rounded-full ring-2 ${person.status}`}
/>
</div>
))}
</div>
)
}
Shape & ring
Round (default), square (`rounded-lg`), and a ringed avatar with `ring-offset`.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
export default function AvatarShapes01() {
return (
<div className="flex items-center gap-6">
{/* Default round */}
<Avatar className="size-12">
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
{/* Square (rounded-lg) */}
<Avatar className="size-12 rounded-lg">
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback className="rounded-lg">CN</AvatarFallback>
</Avatar>
{/* With a ring */}
<Avatar className="ring-primary ring-offset-background size-12 ring-2 ring-offset-2">
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
</div>
)
}
With name
The user-row pattern — an avatar beside a name and email, the second falling back to initials.
Packages
Props
No props documented yet.
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
const people = [
{ src: "https://github.com/shadcn.png", name: "shadcn", email: "[email protected]", fallback: "CN" },
{ src: "", name: "Ada Lovelace", email: "[email protected]", fallback: "AL" },
]
export default function AvatarDetail01() {
return (
<div className="grid gap-4">
{people.map((person, index) => (
<div key={index} className="flex items-center gap-3">
<Avatar>
<AvatarImage src={person.src} alt={person.name} />
<AvatarFallback>{person.fallback}</AvatarFallback>
</Avatar>
<div className="grid gap-0.5">
<p className="text-sm leading-none font-medium">{person.name}</p>
<p className="text-muted-foreground text-xs">{person.email}</p>
</div>
</div>
))}
</div>
)
}
The Shadcn Avatar is the user image — the canonical shadcn/ui avatar built on Radix, with a graceful fallback to initials when the image is missing or still loading. Official ships one demo; the examples below cover the real uses — groups, status dots, sizes, and shapes.
Built on Radix
Avatar wraps Radix Avatar with three parts:
<Avatar>
<AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
<AvatarFallback>CN</AvatarFallback>
</Avatar>
AvatarImage renders only once the image has loaded; until then — or if it fails — AvatarFallback shows. That's the whole point: avatars never break into a busted-image icon. Put initials in the fallback.
Fallbacks & initials
For users without a photo, skip the image (or let it fail) and the AvatarFallback initials fill the circle. Give the fallback a background and text color for colored initials (bg-rose-500 text-white) — a common pattern for distinguishing people in a list. The Fallbacks example shows plain and colored.
Sizes & shapes
Size with a className on Avatar — the default is size-8; use size-6 … size-16 (the Sizes example). For a square avatar, set rounded-lg on the Avatar and AvatarFallback to override the default rounded-full; add ring-2 ring-offset-2 for a ringed look (the Shape & ring example).
Avatar groups
A stacked avatar group is a flex row with a negative gap so they overlap, plus a ring on each so they separate cleanly:
<div className="flex -space-x-2">
<Avatar className="ring-background ring-2">…</Avatar>
…
<Avatar className="ring-background ring-2">
<AvatarFallback>+3</AvatarFallback>
</Avatar>
</div>
The Avatar group example includes the "+N" overflow.
Status & context
Pin a status dot to the avatar by wrapping it in a relative container and absolutely positioning a small ringed rounded-full span at the bottom-right — green for online, amber for away, muted for offline (the Status indicator example). In a list or menu, set the avatar beside a name and email (the With name example) — the pattern this gallery now uses in its Card, Dropdown Menu, and Popover user examples.
Accessibility & theming
Give AvatarImage a meaningful alt (the person's name), or alt="" when the name is already shown beside it. Don't rely on the status dot color alone — pair it with a label. The avatar reads your design tokens — --muted (the fallback background), --background (group rings) — so it follows your theme, including dark mode, with no overrides.
