Avatar

A composable avatar built on Base UI's Avatar primitive. Supports an image with automatic fallback, a status badge, and grouped layouts for displaying multiple avatars.

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

export default function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  )
}

Anatomy

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

<Avatar>
  <AvatarImage src="/user.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Examples

Basic avatar

<Avatar>
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Sizes

Use size to control the avatar dimensions. Available values are "sm" (24px), "default" (32px), and "lg" (40px).

<div className="flex items-center gap-4">
  <Avatar size="sm">
    <AvatarFallback>S</AvatarFallback>
  </Avatar>
  <Avatar size="default">
    <AvatarFallback>M</AvatarFallback>
  </Avatar>
  <Avatar size="lg">
    <AvatarFallback>L</AvatarFallback>
  </Avatar>
</div>

With badge

Use AvatarBadge to overlay a small status indicator on the avatar.

<Avatar>
  <AvatarImage src="/user.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
  <AvatarBadge />
</Avatar>

Grouped avatars

Use AvatarGroup to stack avatars with a negative horizontal offset. Add AvatarGroupCount to show a count of additional avatars.

<AvatarGroup>
  <Avatar>
    <AvatarImage src="/user-1.jpg" alt="User 1" />
    <AvatarFallback>U1</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/user-2.jpg" alt="User 2" />
    <AvatarFallback>U2</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/user-3.jpg" alt="User 3" />
    <AvatarFallback>U3</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+5</AvatarGroupCount>
</AvatarGroup>

API Reference

Avatar

The root wrapper. Renders a circular container with a border overlay.

AvatarImage

The user's profile image. Falls back to AvatarFallback if the image fails to load.

AvatarFallback

Displayed when the image is loading or unavailable. Typically contains initials or an icon.

AvatarBadge

A small circular indicator positioned at the bottom-right of the avatar. Size adapts to the parent avatar's size prop.

AvatarGroup

A flex container that stacks child avatars with a negative horizontal offset and adds a ring to each avatar.

AvatarGroupCount

A circular count indicator for use at the end of an AvatarGroup. Matches the size of sibling avatars.