Avatar

Loading component...

Installation

npx shadcn@latest add avatar

Usage

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

export function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  )
}

Examples

Sizes

Loading component...

Fallbacks

Loading component...

import { User } from "lucide-react"import {  Avatar,  AvatarFallback,  AvatarImage,} from "@/components/ui/avatar"export default function AvatarFallbacks() {  return (    <div className="w-full p-6">      <div className="grid grid-cols-2 md:grid-cols-4 gap-6 max-w-2xl mx-auto">        <div className="text-center space-y-3">          <Avatar>            <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />            <AvatarFallback>CN</AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">With Image</p>            <p className="text-xs text-muted-foreground">Primary display</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar>            <AvatarImage src="/broken-image.png" alt="Broken" />            <AvatarFallback>AB</AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Text Fallback</p>            <p className="text-xs text-muted-foreground">When image fails</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar>            <AvatarFallback>              <User className="size-4" />            </AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Icon Fallback</p>            <p className="text-xs text-muted-foreground">Generic user icon</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar>            <AvatarFallback className="bg-gradient-to-br from-purple-400 to-pink-400 text-white">              JD            </AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Styled Fallback</p>            <p className="text-xs text-muted-foreground">Custom background</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar className="border-2 border-primary">            <AvatarImage src="https://github.com/leerob.png" alt="@leerob" />            <AvatarFallback>LR</AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">With Border</p>            <p className="text-xs text-muted-foreground">Emphasized avatar</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar className="ring-2 ring-green-500 ring-offset-2 ring-offset-background">            <AvatarImage src="https://github.com/evilrabbit.png" alt="@evilrabbit" />            <AvatarFallback>ER</AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Status Ring</p>            <p className="text-xs text-muted-foreground">Online indicator</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar className="rounded-lg">            <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />            <AvatarFallback>CN</AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Square Avatar</p>            <p className="text-xs text-muted-foreground">Rounded corners</p>          </div>        </div>                <div className="text-center space-y-3">          <Avatar className="rounded-none">            <AvatarFallback className="bg-orange-500 text-white font-bold">              42            </AvatarFallback>          </Avatar>          <div>            <p className="text-sm font-medium">Number Badge</p>            <p className="text-xs text-muted-foreground">Count display</p>          </div>        </div>      </div>    </div>  )}

Groups

Loading component...

import { Plus } from "lucide-react"import {  Avatar,  AvatarFallback,  AvatarImage,} from "@/components/ui/avatar"const users = [  { src: "https://github.com/shadcn.png", alt: "@shadcn", fallback: "CN" },  { src: "https://github.com/leerob.png", alt: "@leerob", fallback: "LR" },  { src: "https://github.com/evilrabbit.png", alt: "@evilrabbit", fallback: "ER" },  { src: "https://github.com/vercel.png", alt: "@vercel", fallback: "V" },  { src: "https://github.com/nextjs.png", alt: "@nextjs", fallback: "NJ" },]export default function AvatarGroups() {  return (    <div className="w-full p-6 space-y-8">      <div className="text-center space-y-4">        <h3 className="text-lg font-semibold">Overlapping Stack</h3>        <div className="flex justify-center">          <div className="flex -space-x-3">            {users.slice(0, 4).map((user, index) => (              <Avatar key={index} className="border-2 border-background">                <AvatarImage src={user.src} alt={user.alt} />                <AvatarFallback>{user.fallback}</AvatarFallback>              </Avatar>            ))}            <Avatar className="border-2 border-background bg-muted text-muted-foreground">              <AvatarFallback>+2</AvatarFallback>            </Avatar>          </div>        </div>        <p className="text-sm text-muted-foreground">Team collaboration</p>      </div>      <div className="text-center space-y-4">        <h3 className="text-lg font-semibold">Spaced Group</h3>        <div className="flex justify-center gap-2">          {users.slice(0, 3).map((user, index) => (            <Avatar key={index} className="size-12">              <AvatarImage src={user.src} alt={user.alt} />              <AvatarFallback>{user.fallback}</AvatarFallback>            </Avatar>          ))}        </div>        <p className="text-sm text-muted-foreground">Recent activity</p>      </div>      <div className="text-center space-y-4">        <h3 className="text-lg font-semibold">With Add Button</h3>        <div className="flex justify-center items-center gap-3">          <div className="flex -space-x-2">            {users.slice(0, 3).map((user, index) => (              <Avatar key={index} className="size-10 border-2 border-background">                <AvatarImage src={user.src} alt={user.alt} />                <AvatarFallback>{user.fallback}</AvatarFallback>              </Avatar>            ))}          </div>          <Avatar className="size-10 border-2 border-dashed border-primary/50 bg-primary/5 hover:bg-primary/10 transition-colors cursor-pointer">            <AvatarFallback className="text-primary">              <Plus className="size-4" />            </AvatarFallback>          </Avatar>        </div>        <p className="text-sm text-muted-foreground">Invite collaborators</p>      </div>      <div className="text-center space-y-4">        <h3 className="text-lg font-semibold">Status Indicators</h3>        <div className="flex justify-center gap-6">          <div className="relative">            <Avatar className="size-12">              <AvatarImage src={users[0].src} alt={users[0].alt} />              <AvatarFallback>{users[0].fallback}</AvatarFallback>            </Avatar>            <div className="absolute -bottom-1 -right-1 size-4 bg-green-500 border-2 border-background rounded-full"></div>            <p className="text-xs text-center mt-2 text-muted-foreground">Online</p>          </div>                    <div className="relative">            <Avatar className="size-12">              <AvatarImage src={users[1].src} alt={users[1].alt} />              <AvatarFallback>{users[1].fallback}</AvatarFallback>            </Avatar>            <div className="absolute -bottom-1 -right-1 size-4 bg-yellow-500 border-2 border-background rounded-full"></div>            <p className="text-xs text-center mt-2 text-muted-foreground">Away</p>          </div>                    <div className="relative">            <Avatar className="size-12 grayscale">              <AvatarImage src={users[2].src} alt={users[2].alt} />              <AvatarFallback>{users[2].fallback}</AvatarFallback>            </Avatar>            <div className="absolute -bottom-1 -right-1 size-4 bg-gray-400 border-2 border-background rounded-full"></div>            <p className="text-xs text-center mt-2 text-muted-foreground">Offline</p>          </div>        </div>      </div>      <div className="text-center space-y-4">        <h3 className="text-lg font-semibold">Large Group Counter</h3>        <div className="flex justify-center">          <div className="flex -space-x-4">            {users.slice(0, 3).map((user, index) => (              <Avatar key={index} className="size-14 border-4 border-background">                <AvatarImage src={user.src} alt={user.alt} />                <AvatarFallback>{user.fallback}</AvatarFallback>              </Avatar>            ))}            <Avatar className="size-14 border-4 border-background bg-primary text-primary-foreground">              <AvatarFallback className="text-lg font-bold">+15</AvatarFallback>            </Avatar>          </div>        </div>        <p className="text-sm text-muted-foreground">18 team members</p>      </div>    </div>  )}

API Reference

The root avatar container that manages the image loading state.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for styling.
`children`	`React.ReactNode`	-	AvatarImage and AvatarFallback components.

AvatarImage

Displays the primary avatar image with automatic fallback handling.

Prop	Type	Default	Description
`src`	`string`	-	The image source URL.
`alt`	`string`	-	Alternative text for accessibility.
`className`	`string`	-	Additional CSS classes for styling.
`onLoadingStatusChange`	`(status: "loading" \| "loaded" \| "error") => void`	-	Callback for image loading state changes.

AvatarFallback

Displays when the image fails to load or is loading.

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes for styling.
`delayMs`	`number`	`600`	Delay before showing fallback (prevents flash).
`children`	`React.ReactNode`	-	Fallback content (text, icon, or component).

Implementation Details

Architecture

Built on Radix UI's Avatar primitive with enhanced styling:

Image Loading: Automatic handling of image loading states
Graceful Degradation: Seamless fallback when images fail
Accessibility: Proper ARIA attributes and semantic structure
Performance: Optimized loading with configurable delays

Loading States

The Avatar component handles three distinct loading states:

Loading: Image is being fetched
Loaded: Image successfully displayed
Error: Image failed, fallback shown

<Avatar>
  <AvatarImage 
    src="/image.jpg" 
    onLoadingStatusChange={(status) => {
      console.log('Image status:', status)
    }}
  />
  <AvatarFallback delayMs={600}>
    JD
  </AvatarFallback>
</Avatar>

Size Variants

Common size implementations using Tailwind classes:

Size	Class	Use Case
Extra Small	`size-6`	Compact lists, comments
Small	`size-8`	Default size, inline text
Medium	`size-10`	Cards, navigation
Large	`size-14`	Profile headers, modals
Extra Large	`size-20`	Profile pages, about sections

Best Practices

Image Optimization

Always provide optimized images for better performance:

<Avatar>
  <AvatarImage 
    src="/avatar-400x400.webp"
    alt="User profile picture"
  />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Fallback Content

Create meaningful fallbacks that enhance user experience:

// Text initials (preferred)
<AvatarFallback>JD</AvatarFallback>

// Icon fallback
<AvatarFallback>
  <UserIcon className="size-4" />
</AvatarFallback>

// Custom styled fallback
<AvatarFallback className="bg-gradient-to-br from-purple-400 to-pink-400 text-white">
  JS
</AvatarFallback>

Accessibility

Ensure proper accessibility with descriptive alt text:

<Avatar>
  <AvatarImage 
    src="/avatar.jpg" 
    alt="John Doe, Software Engineer"
  />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Responsive Sizing

Use responsive classes for different screen sizes:

<Avatar className="size-8 sm:size-10 md:size-12">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>U</AvatarFallback>
</Avatar>

Common Use Cases

User Profile

Display user information with avatar and details:

function UserProfile({ user }) {
  return (
    <div className="flex items-center gap-4">
      <Avatar className="size-16">
        <AvatarImage src={user.avatar} alt={user.name} />
        <AvatarFallback>{user.initials}</AvatarFallback>
      </Avatar>
      <div>
        <h3 className="font-semibold">{user.name}</h3>
        <p className="text-muted-foreground">{user.email}</p>
      </div>
    </div>
  )
}

Comment Section

Compact avatars for comments and discussions:

function Comment({ comment }) {
  return (
    <div className="flex gap-3">
      <Avatar className="size-8">
        <AvatarImage src={comment.author.avatar} alt={comment.author.name} />
        <AvatarFallback>{comment.author.initials}</AvatarFallback>
      </Avatar>
      <div className="flex-1">
        <div className="flex items-center gap-2 mb-1">
          <span className="font-medium text-sm">{comment.author.name}</span>
          <span className="text-xs text-muted-foreground">{comment.timestamp}</span>
        </div>
        <p className="text-sm">{comment.content}</p>
      </div>
    </div>
  )
}

Team Directory

Grid layout for team member profiles:

function TeamDirectory({ members }) {
  return (
    <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-6 gap-6">
      {members.map((member) => (
        <div key={member.id} className="text-center space-y-2">
          <Avatar className="size-16 mx-auto">
            <AvatarImage src={member.avatar} alt={member.name} />
            <AvatarFallback>{member.initials}</AvatarFallback>
          </Avatar>
          <div>
            <p className="font-medium text-sm">{member.name}</p>
            <p className="text-xs text-muted-foreground">{member.role}</p>
          </div>
        </div>
      ))}
    </div>
  )
}

User menu with avatar trigger:

function UserMenu({ user }) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="ghost" className="relative h-10 w-10 rounded-full">
          <Avatar className="size-10">
            <AvatarImage src={user.avatar} alt={user.name} />
            <AvatarFallback>{user.initials}</AvatarFallback>
          </Avatar>
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent className="w-56" align="end" forceMount>
        <DropdownMenuLabel>My Account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Profile</DropdownMenuItem>
        <DropdownMenuItem>Settings</DropdownMenuItem>
        <DropdownMenuItem>Logout</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

Advanced Patterns

Avatar Groups

Overlapping avatar stacks for team representation:

function AvatarGroup({ users, max = 4 }) {
  const displayUsers = users.slice(0, max)
  const extraCount = users.length - max

  return (
    <div className="flex -space-x-2">
      {displayUsers.map((user, index) => (
        <Avatar key={user.id} className="border-2 border-background">
          <AvatarImage src={user.avatar} alt={user.name} />
          <AvatarFallback>{user.initials}</AvatarFallback>
        </Avatar>
      ))}
      {extraCount > 0 && (
        <Avatar className="border-2 border-background">
          <AvatarFallback>+{extraCount}</AvatarFallback>
        </Avatar>
      )}
    </div>
  )
}

Status Indicators

Show user online status with colored rings:

function AvatarWithStatus({ user, status }) {
  const statusColors = {
    online: 'bg-green-500',
    away: 'bg-yellow-500',
    offline: 'bg-gray-400'
  }

  return (
    <div className="relative">
      <Avatar className={status === 'offline' ? 'grayscale' : ''}>
        <AvatarImage src={user.avatar} alt={user.name} />
        <AvatarFallback>{user.initials}</AvatarFallback>
      </Avatar>
      <div className={`absolute -bottom-1 -right-1 size-4 rounded-full border-2 border-background ${statusColors[status]}`} />
    </div>
  )
}

Custom Shapes

Non-circular avatars for special use cases:

// Square avatar
<Avatar className="rounded-lg">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>U</AvatarFallback>
</Avatar>

// Hexagonal avatar
<Avatar className="clip-path-hexagon">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>U</AvatarFallback>
</Avatar>

// No rounding (rectangular)
<Avatar className="rounded-none">
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>U</AvatarFallback>
</Avatar>

Accessibility

The Avatar component provides proper semantic structure:

AvatarImage includes alt text for screen readers
AvatarFallback provides alternative text when images fail
Proper focus management for interactive avatars

When used as interactive elements:

<button className="rounded-full focus:outline-none focus:ring-2 focus:ring-primary">
  <Avatar>
    <AvatarImage src="/avatar.jpg" alt="Open user menu" />
    <AvatarFallback>U</AvatarFallback>
  </Avatar>
</button>

Color Contrast

Ensure sufficient contrast for fallback text:

// Good contrast
<AvatarFallback className="bg-primary text-primary-foreground">
  JD
</AvatarFallback>

// Check contrast ratios for custom colors
<AvatarFallback className="bg-purple-600 text-white">
  JD
</AvatarFallback>

Performance Optimization

Image Loading Strategies

// Eager loading for above-the-fold avatars
<AvatarImage src="/avatar.jpg" loading="eager" alt="User" />

// Lazy loading for below-the-fold avatars
<AvatarImage src="/avatar.jpg" loading="lazy" alt="User" />

// Preload critical avatars
useEffect(() => {
  const link = document.createElement('link')
  link.rel = 'preload'
  link.href = '/critical-avatar.jpg'
  link.as = 'image'
  document.head.appendChild(link)
}, [])

Memory Management

For large lists of avatars, consider virtualization:

import { FixedSizeList as List } from 'react-window'

function VirtualizedAvatarList({ users }) {
  const Row = ({ index, style }) => (
    <div style={style} className="flex items-center gap-3 px-4">
      <Avatar>
        <AvatarImage src={users[index].avatar} alt={users[index].name} />
        <AvatarFallback>{users[index].initials}</AvatarFallback>
      </Avatar>
      <span>{users[index].name}</span>
    </div>
  )

  return (
    <List height={400} itemCount={users.length} itemSize={60}>
      {Row}
    </List>
  )
}

Troubleshooting

Common Issues

Images not loading: Check CORS policy and image URLs
Fallback flashing: Adjust delayMs prop on AvatarFallback
Inconsistent sizes: Ensure consistent size classes across components
Poor performance: Optimize images and consider lazy loading

Debugging

<Avatar>
  <AvatarImage 
    src="/avatar.jpg" 
    onLoadingStatusChange={(status) => {
      console.log('Avatar loading status:', status)
    }}
  />
  <AvatarFallback delayMs={0}> {/* Remove delay for debugging */}
    Debug
  </AvatarFallback>
</Avatar>

SEO Considerations

Alt Text: Descriptive alt attributes improve accessibility and SEO
Image Optimization: Properly sized images improve Core Web Vitals
Structured Data: Consider Person schema markup for user profiles
Lazy Loading: Improves page load performance for image-heavy pages
WebP Format: Use modern image formats when possible for better compression

Avatar

Installation

Usage

Examples

Sizes

Fallbacks

Groups

API Reference

Avatar

AvatarImage

AvatarFallback

Implementation Details

Architecture

Loading States

Size Variants

Best Practices

Image Optimization

Fallback Content

Accessibility

Responsive Sizing

Common Use Cases

User Profile

Comment Section

Team Directory

Navigation Menu

Advanced Patterns

Avatar Groups

Status Indicators

Custom Shapes

Accessibility

Keyboard Navigation

Color Contrast

Performance Optimization

Image Loading Strategies

Memory Management

Troubleshooting

Common Issues

Debugging

SEO Considerations

On this page

Avatar

Reactavatar

Reactavatar

Reactavatar

Reactavatar

On this page