Docs › Components › Avatar

Shadcn Avatar

The shadcn/ui Avatar shows a user's photo with a graceful fallback to initials or an icon, styled with Tailwind CSS v4. It handles the loading and error states of the image for you. Avatars appear in testimonials, team sections, and app headers across ShadcnStore blocks.

Key features

• Image with an automatic fallback to initials or an icon.
• Handles image loading and error states for you.
• Any size via Tailwind width and height classes.
• Composes into overlapping avatar groups.

Installation

npx shadcn@latest add avatar

Usage

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

export function Example() {
  return (
    <Avatar>
      <AvatarImage src="/user.png" alt="Colin Nolan" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  )
}

The fallback shows while the image loads and if it fails, so users never see a broken image.

Sizes

Set the size with width and height utilities:

<Avatar className="size-6">…</Avatar>
<Avatar className="size-12">…</Avatar>

Avatar group

<div className="flex -space-x-2">
  <Avatar className="ring-2 ring-background">…</Avatar>
  <Avatar className="ring-2 ring-background">…</Avatar>
</div>

Anatomy

Part	Purpose
Avatar	Root; sets the shape and size.
AvatarImage	The user's image, with src and alt.
AvatarFallback	Initials or icon shown when the image is unavailable.

Accessibility

• Always give AvatarImage a meaningful alt, usually the person's name.
• Make the fallback text (initials) meaningful, since screen readers may read it when the image is absent.
• If an avatar is a link or button, ensure the interactive element has its own accessible name.

When to use the Avatar

Use an Avatar to represent a person or account: comment authors, team members, testimonial sources, and the account menu in a header. For a brand or product logo, use a plain image. For status next to a name, pair the avatar with a Badge.

Used in these blocks

• Testimonials: reviewer photos.
• Teams: team member photos.
• App shells: account avatar in the header.

Related components

An Avatar sits in a Card header, triggers a Dropdown Menu for the account menu, pairs with a Badge for presence or status, and appears in every Message turn in a conversation thread.

FAQ

What is the shadcn avatar used for?

The Avatar shows a user's photo, with initials or an icon as a fallback when the image is missing or still loading.

How does the avatar fallback work?

AvatarFallback renders when AvatarImage fails to load or is not provided, so you can show initials or an icon instead of a broken image.

How do I make an avatar group?

Place several avatars in a flex row with a small negative margin so they overlap, and add a ring for separation.

How do I change the avatar size?

Apply Tailwind width and height classes such as size-6 or size-12 to the Avatar root.