Avatar

A circular user image with a graceful fallback to initials when no image is available. Supports three sizes, an optional badge, and group stacking. Built on @base-ui/react/avatar.

Anatomy

<Avatar> is the root circle — pass size ("sm", "default", "lg") to control its dimensions. AvatarImage renders the photo; it waits for the image to load before showing. AvatarFallback shows until the image is ready — use initials here. AvatarBadge is an absolute-positioned indicator (online dot, notification count).

SMJDLG
size="sm" (24px)size="default" (32px)size="lg" (40px)

Examples

With image

JDABSK

With badge

ONOFIC

Group stacking

U1U2U3
+4

All sizes — fallback only

SMsm
MDdefault
LGlg

Design Guidelines

Do

  • Always provide a fallback. Images fail — AvatarFallbackwith initials ensures there's always something meaningful to display.
  • Use AvatarGroup for team displays. Stacking avatars with a count (AvatarGroupCount) communicates collaboration without listing every member.
  • Match avatar size to context. Use sm inline (in tables, lists), default for most UI, and lg for profile headers or comment threads.

Don't

  • Don't use more than one badge per avatar. AvatarBadge is a single indicator — stacking two statuses creates an unreadable dot cluster.
  • Don't use avatars without alt text. Always pass a descriptive alt to AvatarImage— it's the only accessible label for the image.
  • Don't show more than 5 avatars in a group. Cap the stack at 4–5 and use AvatarGroupCount for the remainder to keep the UI compact.

Developer Reference

Accessibility & Behavior

  • AvatarImage waits for the image to fully load before rendering — AvatarFallback is shown in the meantime.
  • The size prop on Avatar sets a data-size attribute used by child components (AvatarFallback, AvatarBadge) to scale themselves automatically.
  • AvatarGroup applies negative margin spacing and a ring outline to each child avatar to create the stacked look.
  • AvatarGroupCount inherits its size from the nearest AvatarGroup via the group-has-data-[size=*] selector.

Usage

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

// Basic with image + fallback
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="Jane Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

// Sizes: "sm" | "default" | "lg"
<Avatar size="lg">
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

// With online badge
<Avatar>
  <AvatarFallback>JD</AvatarFallback>
  <AvatarBadge className="bg-green-500" />
</Avatar>

// Group stacking
<AvatarGroup>
  <Avatar><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar><AvatarFallback>C</AvatarFallback></Avatar>
  <AvatarGroupCount>+4</AvatarGroupCount>
</AvatarGroup>