Shadcn Avatar Components

Shadcn Avatar Component

The Shadcn Avatar is a small, usually round image that represents a person, a team or an account. It shows a profile photo when one is available and falls back to initials or an icon when it is not, so the interface never shows an empty circle or a broken image. Navigation bars, comment threads, team lists, chat apps and dashboards all rely on it to make people recognizable at a glance.

Need a stack of overlapping faces with a +4 count, an online dot or a camera overlay for changing the profile photo? Those patterns and more are ready here as shadcn avatar examples written in React and styled with shadcn/ui and Tailwind CSS, and each one works with both Radix UI and Base UI primitives.

What is the Shadcn Avatar Component?

An avatar is an image with a built-in loading strategy. The primitive tries to load the image, and only when it has loaded successfully does it replace the fallback. While the image is loading, or if the URL is missing or broken, the fallback stays visible. That makes it more than a styled img tag: you get a stable layout and a sensible placeholder without writing any loading logic yourself.

Use an avatar when the thing you show is an identity: a user, an author or a workspace. If you only need a short status label next to a name, a Badge is the better fit, and if you want to show a full profile preview on hover, wrap the avatar in a Hover Card or a Popover. For a list of people with names and actions in rows, combine avatars with the Item component.

Anatomy of the Shadcn Avatar

21 Shadcn Avatar Variants

Each avatar variant listed here is previewed live at the top of this page, together with its source code and install command.

• Image, initials and icon: The basic avatar with a photo, an initials only fallback and a user icon fallback, plus a colorful icon version on a brand background.
• Status and badges: An online dot with AvatarBadge, a verified check icon in the corner, a numeric notification badge and a colored ring for status.
• Rounded square: Swaps the circle for rounded corners on the root, image and fallback, a common choice for workspaces and company logos.
• Avatar groups: Overlapping stacks of avatars, with an optional +4 count, a trusted by label, and an empty collaborators state.
• With tooltip: Shows the person's name in a tooltip on hover, for a single avatar or for every avatar inside a group.
• With dropdown menu and popover: A user button that opens an account menu, a group whose +4 count lists the hidden members, and a profile card in a popover.
• Upload and loading overlays: A camera overlay that appears on hover for changing the photo, and a spinner overlay while a new image is uploading.
• Avatar with text: An avatar next to a name and a role, ready for comment headers, author bylines and member lists.

How to Install the Shadcn Avatar Component

Set up shadcn/ui in your project if you have not already, then add the Shadcn UI Kit registry to your components.json once:

{
  "registries": {
    "@shadcnuikit": "https://shadcnuikit.com/r/{name}.json"
  }
}

Then install a avatar variant by its name:

npx shadcn@latest add @shadcnuikit/avatar1

The same command works with pnpm dlx, yarn dlx and bunx --bun. Each variant has a copy button for every package manager, and the code is added to your project as plain React and Tailwind CSS that you can edit freely.

How to Use the Shadcn Avatar Component

Import the parts from your components/ui folder. Always add an AvatarFallback, and give the image a meaningful alt text, usually the person's name.

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

export function TeamAvatars() {
  return (
    <div className="flex items-center gap-6">
      <Avatar size="lg">
        <AvatarImage src="/avatars/jane.png" alt="Jane Cooper" />
        <AvatarFallback>JC</AvatarFallback>
        <AvatarBadge className="bg-green-500">
          <span className="sr-only">Online</span>
        </AvatarBadge>
      </Avatar>

      <AvatarGroup>
        <Avatar>
          <AvatarImage src="/avatars/devon.png" alt="Devon Lane" />
          <AvatarFallback>DL</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/leslie.png" alt="Leslie Alexander" />
          <AvatarFallback>LA</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
    </div>
  )
}

Why Use the Shadcn Avatar Component

• No broken images: The image only appears after it loads, and the fallback covers slow networks, missing URLs and deleted photos.
• Consistent sizes: The size prop keeps avatars, badges and group counts in proportion, so you do not have to size every part by hand.
• Groups built in: AvatarGroup and AvatarGroupCount handle overlapping, separating rings and the remaining count without extra CSS.
• Composable: An avatar drops into buttons, tooltips, menus and popovers, so user menus and profile previews take a few lines.
• Theme aware: Fallback colors, borders and rings use your theme variables and follow dark mode automatically.

Common Avatar Use Cases

• User menus: The avatar in the top right corner of an app that opens profile, settings and log out actions.
• Comments and chat: Author avatars next to messages, replies and reviews so readers can follow who said what.
• Team and collaborator lists: Stacked avatars on project cards and documents that show who has access or is online.
• Presence indicators: Online, away and busy states shown with a colored badge or ring around the photo.
• Profile settings: A large avatar with a hover overlay that lets users upload or change their photo.
• Social proof: A row of customer avatars next to a line such as trusted by 10K+ developers on a landing page.

Customizing the Shadcn Avatar

Change the size with the size prop or any Tailwind size class on the root, and change the shape by overriding the rounding on the root, the image and the fallback together. Every part carries a data-slot attribute, so one class on Avatar can style the image and fallback inside it. Fallback and ring colors come from your theme variables, and you can build a matching palette with the free Theme Generator.

This turns an avatar into a rounded square:

<Avatar className="rounded-lg after:rounded-lg **:data-[slot=avatar-image]:rounded-lg **:data-[slot=avatar-fallback]:rounded-lg">
  <AvatarImage src="/logos/acme.png" alt="Acme Inc." />
  <AvatarFallback>AC</AvatarFallback>
</Avatar>

Avatar Accessibility

The avatar itself is not interactive, so the most important thing is the text alternative. Give AvatarImage an alt with the person's name. When the avatar sits right next to the visible name, an empty alt avoids screen readers announcing the name twice. Status dots, rings and icons carry no text of their own, so add a sr-only label such as "Online" or "Verified", as the online and verified variants on this page do.

When an avatar opens a menu or a profile card, the trigger must be a real button so it is reachable with Tab and can be activated with Enter or Space. Keyboard handling then comes from the Dropdown Menu or Popover, not from the avatar.

Avatar Best Practices

• Always render a fallback; initials are more useful than a generic icon when you know the name.
• Use the same avatar size for the same role across the app, for example sm in lists and lg in profile headers.
• Limit groups to 4 or 5 visible avatars and show the rest with AvatarGroupCount.
• Serve square, appropriately sized images so photos stay sharp without downloading large files.
• Do not rely on color alone for status; pair the dot with a screen reader label or a tooltip.
• Wrap interactive avatars in a Button so focus styles and keyboard support work as expected.

Components Related to Avatar

Shadcn Avatar FAQ

Looking for something else? Browse all shadcn/ui components or ready-made UI blocks built with them.