User image with intelligent loading states, fallback initials or icon, flexible sizing, status badges, and grouping.

Avatar

The Avatar component displays a user's profile image with graceful fallbacks. It intelligently handles image loading states and shows a fallback (like initials or an icon) when the image is missing or fails to load.

Use Avatar anywhere you need a compact representation of a user or entity (navigation bars, lists, comments, menus). Provide meaningful alt text, and always include a fallback.

Features

Three built-in sizes via the size prop: sm (24px), default (32px), lg (40px)
Intelligent image loading with automatic fallback display
Optional delay for fallback to prevent flicker
AvatarBadge for status indicators that scale with the avatar size
AvatarGroup and AvatarGroupCount for overlapping avatar stacks
Accessible semantics and best practices
Works with text initials or icons as fallback

Usage

import {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarBadge,
  AvatarGroup,
  AvatarGroupCount,
} from '@loke/design-system/avatar';

export default function Example() {
  return (
    <Avatar>
      <AvatarImage src="https://example.com/profile.jpg" alt="Jane Doe" />
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  );
}

Tips:

Use the size prop (sm, default, lg) for standard sizes
Use initials or an icon for the fallback; consider delayMs to reduce flicker
Ensure alt text clearly describes the represented user or entity

Props

Avatar

Prop

Type

AvatarImage

Prop

Type

AvatarFallback

Prop

Type

AvatarBadge

A small status indicator positioned at the bottom-right of the avatar. Scales automatically with the avatar's size prop.

Prop

Type

AvatarGroup

A container that arranges child avatars in an overlapping stack. Automatically adds a ring to each avatar for visual separation.

Prop

Type

AvatarGroupCount

A count indicator for avatar groups (e.g., "+3 more"). Automatically matches the size of sibling avatars.

Prop

Type

Examples

Default

<Avatar>
  <AvatarImage alt="@shadcn" src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

With fallback (invalid image)

<Avatar>
  <AvatarImage alt="Invalid Image" src="https://invalid-image-url.png" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Sizes

Use the size prop instead of custom width/height classes.

SMMDLG

<div className="flex items-center gap-4">
  <Avatar size="sm">…</Avatar>
  <Avatar>…</Avatar>
  <Avatar size="lg">…</Avatar>
</div>

Delayed fallback

<Avatar>
  <AvatarImage alt="Invalid Image" src="https://invalid-image-url.png" />
  <AvatarFallback delayMs={600}>Appears after 600ms</AvatarFallback>
</Avatar>

Badge

Add AvatarBadge inside an Avatar to show a status indicator. At lg size, the badge can display an icon.

CNCN

<Avatar>
  <AvatarImage alt="@shadcn" src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge />
</Avatar>

<Avatar size="lg">
  <AvatarImage alt="@shadcn" src="https://github.com/shadcn.png" />
  <AvatarFallback>CN</AvatarFallback>
  <AvatarBadge>
    <Check />
  </AvatarBadge>
</Avatar>

Group / Stack

Use AvatarGroup to stack avatars with overlap and AvatarGroupCount for the overflow count.

CNJDSK

<AvatarGroup>
  <Avatar>
    <AvatarImage alt="@shadcn" src="https://github.com/shadcn.png" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar>…</Avatar>
  <Avatar>…</Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>

Group sizes

AvatarGroupCount automatically matches the size of sibling avatars.

CNJD

<AvatarGroup>
  <Avatar size="sm"><AvatarFallback>CN</AvatarFallback></Avatar>
  <Avatar size="sm"><AvatarFallback>JD</AvatarFallback></Avatar>
  <AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>

<AvatarGroup>
  <Avatar size="lg"><AvatarFallback>CN</AvatarFallback></Avatar>
  <Avatar size="lg"><AvatarFallback>JD</AvatarFallback></Avatar>
  <AvatarGroupCount>+2</AvatarGroupCount>
</AvatarGroup>

Icon fallback

<Avatar>
  <AvatarFallback>
    <User className="size-4" />
  </AvatarFallback>
</Avatar>

Custom colors

ABCDEFGH

<div className="flex items-center gap-4">
  <Avatar className="bg-blue-500 text-white"><AvatarFallback>AB</AvatarFallback></Avatar>
  <Avatar className="bg-green-500 text-white"><AvatarFallback>CD</AvatarFallback></Avatar>
  <Avatar className="bg-purple-500 text-white"><AvatarFallback>EF</AvatarFallback></Avatar>
  <Avatar className="bg-amber-500 text-white"><AvatarFallback>GH</AvatarFallback></Avatar>
</div>

Error handling

MissingMissing image source

404Invalid image URL

<div className="flex flex-col gap-4">
  <div className="flex items-center gap-4">
    <Avatar>
      <AvatarImage alt="Missing Image" src="" />
      <AvatarFallback>Missing</AvatarFallback>
    </Avatar>
    <span>Missing image source</span>
  </div>
  <div className="flex items-center gap-4">
    <Avatar>
      <AvatarImage alt="404 Image" src="https://invalid-image-url.png" />
      <AvatarFallback>404</AvatarFallback>
    </Avatar>
    <span>Invalid image URL</span>
  </div>
</div>

Non-circular avatars

<Avatar className="rounded-md">
  <AvatarImage alt="@shadcn" className="rounded-md" src="https://github.com/shadcn.png" />
  <AvatarFallback className="rounded-md">CN</AvatarFallback>
</Avatar>

Accessibility

Provide meaningful alt text that identifies the person or entity
Ensure fallback content is legible and meets contrast guidelines
Avatars are typically decorative, but when used as buttons/links, add appropriate ARIA labels
AvatarBadge is purely visual; pair it with a text label or tooltip if the status must be conveyed to screen readers

Best practices

Always include AvatarFallback for reliability
Use short, recognizable initials or a clear icon for the fallback
Prefer the size prop over custom width/height classes for consistency
Use AvatarGroup instead of manually building overlapping layouts
Prefer a slight fallback delay to reduce flicker for fast connections
Keep shapes consistent (circular or rounded) within the same UI context

Avatar

On this page