Avatar

A user profile image with a fallback (usually initials) rendered when the image is missing or fails to load. Built on Radix UI Avatar — AvatarFallback accepts a delayMs prop to avoid flashing during fast loads.

Image + fallback

OCJD

Sizes

SMMDLG

With status dot

Stacked

OCABJD+4

Installation

pnpm

pnpm dlx @hex-core/cli add avatar

Stack of avatars

Overlapping team / collaborator avatars with a ring to separate them from the background

tsx

<div className="flex items-center">
  <Avatar className="ring-2 ring-background">
    <AvatarImage src="https://i.pravatar.cc/80?img=1" alt="Ada Lovelace" />
    <AvatarFallback>AL</AvatarFallback>
  </Avatar>
  <Avatar className="-ml-2 ring-2 ring-background">
    <AvatarImage src="https://i.pravatar.cc/80?img=2" alt="Grace Hopper" />
    <AvatarFallback>GH</AvatarFallback>
  </Avatar>
  <Avatar className="-ml-2 ring-2 ring-background">
    <AvatarImage src="https://i.pravatar.cc/80?img=3" alt="Margaret Hamilton" />
    <AvatarFallback>MH</AvatarFallback>
  </Avatar>
  <span className="ml-3 text-sm text-muted-foreground">+4 others</span>
</div>

With status indicator

Online presence dot positioned in the bottom-right corner

tsx

<div className="relative inline-block">
  <Avatar>
    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <span
    className="absolute bottom-0 right-0 h-2.5 w-2.5 rounded-full bg-emerald-500 ring-2 ring-background"
    aria-label="Online"
    role="status"
  />
</div>

API Reference

Prop	Type	Default	Description
`className`	`string`	—	Additional CSS classes on the root

AI Guidance

When to use

Use for user profile images: headers, comments, user lists. Always include AvatarFallback for accessibility and loading states.

When not to use

Don't use for decorative icons (use an <img> or icon component). Don't use for product/brand images (use <img> with proper sizing).

Common mistakes

Missing alt text on AvatarImage
No AvatarFallback — shows nothing when image is missing or errors
Omitting delayMs on AvatarFallback causes flicker for fast-loading images
Using for non-circular images (override rounded-full if needed)

Accessibility

AvatarImage requires alt text. AvatarFallback renders initials or an icon — ensure the visible text is meaningful.

Related components

Token budget: 250

Verified against @hex-core/components@1.12.0

Edit this page on GitHub