Avatar

Data Display
User

User profile images with automatic fallbacks. Built on Radix UI for consistent behavior.

Preview

Avatar with image and fallback

CNJD

Sizes

Four avatar sizes available

SM

Small (32px)

MD

Medium (40px)

LG

Large (48px)

XL

XL (64px)

Fallback States

Fallback displays when image fails to load

ABJDMKTS

Use initials as fallback for a personal touch

Avatar Group

Stack avatars for team displays

Overlapping avatars

CNJDMK+5

With User Info

Common avatar + name patterns

CN

John Doe

john@example.com

AB

Alice Brown

Product Designer

Props

Avatar component API reference

PropTypeDefaultDescription
size'sm' | 'md' | 'lg' | 'xl''md'Avatar size
classNamestringAdditional CSS classes

AvatarImage Props

PropTypeDefaultDescription
srcstringImage source URL
altstringAlt text for accessibility

AvatarFallback Props

PropTypeDefaultDescription
childrenReactNodeFallback content (usually initials)
delayMsnumberDelay before showing fallback

Usage

Import and implementation example

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

export default function Example() {
  return (
    <>
      {/* Basic avatar with image */}
      <Avatar>
        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
        <AvatarFallback>CN</AvatarFallback>
      </Avatar>

      {/* Fallback only */}
      <Avatar>
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>

      {/* Different sizes */}
      <Avatar size="sm"><AvatarFallback>SM</AvatarFallback></Avatar>
      <Avatar size="md"><AvatarFallback>MD</AvatarFallback></Avatar>
      <Avatar size="lg"><AvatarFallback>LG</AvatarFallback></Avatar>
      <Avatar size="xl"><AvatarFallback>XL</AvatarFallback></Avatar>

      {/* Avatar group with overlap */}
      <div className="flex -space-x-3">
        <Avatar className="border-2 border-white">
          <AvatarFallback>A</AvatarFallback>
        </Avatar>
        <Avatar className="border-2 border-white">
          <AvatarFallback>B</AvatarFallback>
        </Avatar>
        <Avatar className="border-2 border-white">
          <AvatarFallback>+3</AvatarFallback>
        </Avatar>
      </div>

      {/* With user info */}
      <div className="flex items-center gap-3">
        <Avatar>
          <AvatarImage src="/user.jpg" />
          <AvatarFallback>UN</AvatarFallback>
        </Avatar>
        <div>
          <p className="font-medium">User Name</p>
          <p className="text-sm text-slate-500">user@email.com</p>
        </div>
      </div>
    </>
  )
}

Features

Built-in functionality

  • Automatic fallback: Shows initials if image fails to load
  • Four sizes: Small (32px), medium (40px), large (48px), XL (64px)
  • Circular design: Full border radius for perfect circles
  • Image optimization: Uses object-cover for proper scaling
  • Radix UI primitives: Built on accessible components
  • Fallback delay: Optional delay before showing fallback
  • Composable: Combine with other components easily
  • Dark mode: Full dark mode support

Accessibility

Accessibility considerations

ARIA Attributes

Uses role="img" when displaying imageAlt text passed to AvatarImageFallback is decorative when image is present

Keyboard Navigation

KeyAction
N/AAvatar is not focusable by default

Notes

  • Always provide alt text for profile images
  • Use meaningful initials for fallback
  • Consider adding aria-label for avatar groups
  • Pair with visible name when possible