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

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

Intelligent image loading with automatic fallback display
Flexible sizing and shape via utility classes
Optional delay for fallback to prevent flicker
Accessible semantics and best practices
Works with text initials or icons as fallback

Usage

import { Avatar, AvatarImage, AvatarFallback } 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:

Adjust size via className (e.g., h-8 w-8, h-14 w-14)
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

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

SMMDLG

<div className="flex items-center gap-4">
  <Avatar className="h-8 w-8">…</Avatar>
  <Avatar>…</Avatar>
  <Avatar className="h-14 w-14">…</Avatar>
</div>

Delayed fallback

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

Group / Stack

CNJDSK+3

<div className="-space-x-2 flex">
  <Avatar className="border-2 border-background">…</Avatar>
  <Avatar className="border-2 border-background">…</Avatar>
  <Avatar className="border-2 border-background">…</Avatar>
  <Avatar className="border-2 border-background bg-muted flex items-center justify-center">
    <span className="text-xs font-medium">+3</span>
  </Avatar>
</div>

Icon fallback

<Avatar>
  <AvatarFallback>
    <User className="h-6 w-6" />
  </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

Best practices

Always include AvatarFallback for reliability
Use short, recognizable initials or a clear icon for the fallback
Size appropriately for the UI context; avoid oversized avatars in dense lists
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