Skip to Content
Dashflow Logo

Avatar Component

A comprehensive guide to using the Avatar component with variants, sizes, examples, and best practices.

Overview

The Avatar component displays user profile pictures with intelligent fallback support and multiple variants. It's designed to represent users in interfaces, automatically showing their profile image when available and gracefully falling back to initials, icons, or custom content when the image fails to load or is unavailable.

Basic Usage

import { Avatar } from '@dashflowx/core'


export default function AvatarExample() {
  return (
    <Avatar 
      imageSrc="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face"
      imageAlt="John Doe"
      fallback={<span>JD</span>}
      variant="basic"
      size="md"
    />
  )
}

Preview:

JD

Variants

Basic Avatar

Standard avatar with rounded corners and clean design.

<Avatar 
  variant="basic"
  imageSrc="https://images.unsplash.com/photo-1494790108755-2616b612b786?w=32&h=32&fit=crop&crop=face"
  imageAlt="Jane Smith"
  fallback={<span>JS</span>}
  size="md"
/>

Preview:

JS

Rounded Avatar

Fully rounded avatar with circular design.

<Avatar 
  variant="rounded"
  imageSrc="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=32&h=32&fit=crop&crop=face"
  imageAlt="John Doe"
  fallback={<span>JD</span>}
  size="md"
/>

Preview:

JD

Square Avatar

Square avatar with sharp corners.

<Avatar 
  variant="square"
  imageSrc="https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=32&h=32&fit=crop&crop=face"
  imageAlt="Sarah Wilson"
  fallback={<span>SW</span>}
  size="md"
/>

Preview:

SW

Ring Avatar

Avatar with a ring border around it.

<Avatar 
  variant="ring"
  imageSrc="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face"
  imageAlt="Mike Johnson"
  fallback={<span>MJ</span>}
  size="md"
/>

Preview:

MJ

Sizes

Small (sm)

Compact avatar for tight spaces.

<Avatar 
  variant="basic"
  imageSrc="https://images.unsplash.com/photo-1494790108755-2616b612b786?w=24&h=24&fit=crop&crop=face"
  imageAlt="Small Avatar"
  fallback={<span>SA</span>}
  size="sm"
/>

Preview:

SA

Medium (md) - Default

Standard size for most use cases.

<Avatar 
  variant="basic"
  imageSrc="https://images.unsplash.com/photo-1494790108755-2616b612b786?w=32&h=32&fit=crop&crop=face"
  imageAlt="Medium Avatar"
  fallback={<span>MA</span>}
  size="md"
/>

Preview:

MA

Large (lg)

Larger avatar for prominent display.

<Avatar 
  variant="basic"
  imageSrc="https://images.unsplash.com/photo-1494790108755-2616b612b786?w=48&h=48&fit=crop&crop=face"
  imageAlt="Large Avatar"
  fallback={<span>LA</span>}
  size="lg"
/>

Preview:

LA

Extra Large (xl)

Extra large avatar for hero sections.

<Avatar 
  variant="basic"
  imageSrc="https://images.unsplash.com/photo-1494790108755-2616b612b786?w=64&h=64&fit=crop&crop=face"
  imageAlt="Extra Large Avatar"
  fallback={<span>XL</span>}
  size="xl"
/>

Preview:

XL

Props

PropTypeDefaultDescription
imageSrcstring-The URL of the avatar image
imageAltstring-Alt text for the avatar image (required for accessibility)
fallbackJSX.Element'UD'Fallback content to display when image fails to load
variant'basic' | 'rounded' | 'square' | 'ring''basic'The visual style variant of the avatar
size'sm' | 'md' | 'lg' | 'xl''md'The size of the avatar
imageClassNamestring-Custom CSS classes for the image element
fallbackClassNamestring-Custom CSS classes for the fallback element

Examples

Professional Profile with Ring Variant

<Avatar 
  variant="ring"
  imageSrc="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=64&h=64&fit=crop&crop=face"
  imageAlt="Professional headshot of John Doe"
  fallback={
    <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-gray-600 to-gray-700 text-white font-semibold">
      JD
    </div>
  }
  size="lg"
/>

Preview:

JD

Team Member with Square Variant

<Avatar 
  variant="square"
  imageSrc="https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=32&h=32&fit=crop&crop=face"
  imageAlt="Sarah Wilson"
  fallback={
    <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-green-500 to-green-600 text-white font-medium text-xs">
      SW
    </div>
  }
  size="md"
/>

Preview:

SW

Guest User with Rounded Variant

<Avatar 
  variant="rounded"
  imageSrc=""
  imageAlt="Guest User"
  fallback={
    <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-purple-500 to-purple-600 text-white font-medium">
      GU
    </div>
  }
  size="sm"
/>

Preview:

GU

Custom Styling with imageClassName and fallbackClassName

<Avatar 
  variant="ring"
  imageSrc="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=48&h=48&fit=crop&crop=face"
  imageAlt="Custom Styled Avatar"
  fallback="CS"
  size="lg"
  imageClassName="shadow-lg border-2 border-blue-300"
  fallbackClassName="bg-gradient-to-br from-blue-500 to-blue-600 text-white font-bold text-lg"
/>

Preview:

CS

Advanced Custom Styling

<Avatar 
  variant="square"
  imageSrc="https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=32&h=32&fit=crop&crop=face"
  imageAlt="Advanced Styled Avatar"
  fallback="AS"
  size="md"
  imageClassName="rounded-lg shadow-md hover:shadow-xl transition-shadow duration-300"
  fallbackClassName="bg-gradient-to-br from-purple-500 to-purple-700 text-white font-semibold text-sm rounded-lg"
/>

Preview:

AS

Common Use Cases

User Profile with Info

<div className="flex items-center space-x-3 p-4 bg-white rounded-lg shadow-sm">
  <Avatar 
    variant="ring"
    imageSrc={user.profileImage}
    imageAlt={`${user.name}'s profile picture`}
    fallback={
      <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-primary-light to-primary text-white font-semibold">
        {user.initials}
      </div>
    }
    size="lg"
  />
  <div className="flex-1">
    <p className="text-sm font-medium text-gray-900">{user.name}</p>
    <p className="text-xs text-gray-500">{user.email}</p>
    <p className="text-xs text-gray-400">{user.role}</p>
  </div>
</div>

Team Members Grid with Different Variants

<div className="grid grid-cols-2 gap-4">
  {teamMembers.map((member, index) => {
    const variants = ['basic', 'rounded', 'square', 'ring'];
    const variant = variants[index % variants.length] as 'basic' | 'rounded' | 'square' | 'ring';
    
    return (
      <div key={member.id} className="flex items-center space-x-3 p-3 bg-gray-50 rounded-lg">
        <Avatar 
          variant={variant}
          imageSrc={member.avatar}
          imageAlt={`${member.name}'s avatar`}
          fallback={
            <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-500 to-blue-600 text-white font-medium text-sm">
              {member.initials}
            </div>
          }
          size="md"
        />
        <div>
          <p className="text-sm font-medium">{member.name}</p>
          <p className="text-xs text-gray-500">{member.position}</p>
          <p className="text-xs text-gray-400 capitalize">{variant}</p>
        </div>
      </div>
    );
  })}
</div>
<header className="flex items-center justify-between p-4 bg-white border-b border-gray-200">
  <div className="flex items-center space-x-4">
    <h1 className="text-xl font-semibold text-gray-900">Dashboard</h1>
    <nav className="flex space-x-6">
      <a href="#" className="text-gray-600 hover:text-gray-900">Projects</a>
      <a href="#" className="text-gray-600 hover:text-gray-900">Tasks</a>
      <a href="#" className="text-gray-600 hover:text-gray-900">Reports</a>
    </nav>
  </div>
  <div className="flex items-center space-x-3">
    <span className="text-sm text-gray-600">Welcome back, {currentUser.name}</span>
    <Avatar 
      variant="basic"
      imageSrc={currentUser.avatar}
      imageAlt={`${currentUser.name}'s avatar`}
      fallback={
        <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-primary-light to-primary text-white font-semibold">
          {currentUser.initials}
        </div>
      }
      size="lg"
    />
  </div>
</header>

Accessibility

The Avatar component includes comprehensive accessibility features:

  • Alt text: Required imageAlt attribute for screen readers
  • Fallback content: Meaningful fallback when images fail to load
  • Semantic structure: Uses appropriate HTML elements
  • Focus management: Proper focus handling when interactive
  • ARIA support: Compatible with assistive technologies
  • Size variants: Appropriate sizing for different contexts

Best Practices

Descriptive Alt Text

Use specific, descriptive alt text that identifies the person.

// ❌ Bad - Generic alt text
<Avatar imageSrc={user.photo} imageAlt="Photo" />


// ✅ Good - Descriptive alt text
<Avatar imageSrc={user.photo} imageAlt="John Doe's professional headshot" />

Consistent Variant Usage

Use consistent variants across your application for similar contexts.

// ✅ Good - Consistent variant for user profiles
<Avatar variant="ring" fallback={<span className="font-semibold text-white">JD</span>} />
<Avatar variant="ring" fallback={<span className="font-semibold text-white">JS</span>} />
<Avatar variant="ring" fallback={<span className="font-semibold text-white">AB</span>} />

Appropriate Size Selection

Choose sizes that fit the context and importance.

// ✅ Good - Size hierarchy
<Avatar size="sm" /> {/* For lists and compact views */}
<Avatar size="md" /> {/* For standard user interfaces */}
<Avatar size="lg" /> {/* For profile headers and important displays */}
<Avatar size="xl" /> {/* For hero sections and prominent features */}

Optimized Image Sizing

Use appropriately sized images for better performance and quality.

// ✅ Good - Optimized image size with face detection
<Avatar 
  imageSrc="https://example.com/avatar.jpg?w=64&h=64&fit=crop&crop=face"
  imageAlt="User avatar"
  fallback={<span>U</span>}
  size="lg"
/>

Meaningful Fallback Content

Always provide meaningful fallback content that represents the user.

// ✅ Good - Meaningful fallback with user initials
<Avatar 
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={
    <span className="font-semibold text-white">
      {user.name.split(' ').map(n => n[0]).join('')}
    </span>
  }
/>

Variant-Specific Styling

Use variants to convey different meanings or contexts.

// ✅ Good - Variant-based styling
const getAvatarVariant = (userRole) => {
  switch (userRole) {
    case 'admin': return 'ring';
    case 'moderator': return 'rounded';
    case 'user': return 'basic';
    default: return 'square';
  }
};


<Avatar 
  variant={getAvatarVariant(user.role)}
  fallback={<span>{user.initials}</span>}
/>

Customization

e Variants

Create different avatar sizes using the size prop:

// Small avatar (24x24)
<Avatar 
  size="sm"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="text-xs font-medium">{user.initials}</span>}
/>


// Medium avatar (32x32) - Default
<Avatar 
  size="md"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="text-sm font-medium">{user.initials}</span>}
/>


// Large avatar (48x48)
<Avatar 
  size="lg"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="text-base font-semibold">{user.initials}</span>}
/>


// Extra large avatar (64x64)
<Avatar 
  size="xl"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="text-lg font-bold">{user.initials}</span>}
/>

Custom Styling with imageClassName and fallbackClassName

Use the imageClassName and fallbackClassName props to apply custom styling:

// Custom image styling
<Avatar 
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback="JD"
  imageClassName="shadow-lg border-2 border-blue-300 rounded-full"
  fallbackClassName="bg-gradient-to-br from-blue-500 to-blue-600 text-white font-bold"
/>


// Advanced custom styling
<Avatar 
  variant="ring"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback="CS"
  size="lg"
  imageClassName="shadow-xl border-4 border-purple-300 hover:scale-105 transition-transform"
  fallbackClassName="bg-gradient-to-br from-purple-500 to-purple-700 text-white font-semibold text-lg"
/>

Variant Combinations

Mix and match variants with sizes for different use cases:

// Professional profile - Large ring variant
<Avatar 
  variant="ring"
  size="lg"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="font-semibold text-white">{user.initials}</span>}
/>


// Team member - Medium rounded variant
<Avatar 
  variant="rounded"
  size="md"
  imageSrc={member.avatar}
  imageAlt={member.name}
  fallback={<span className="font-medium text-white">{member.initials}</span>}
/>


// Compact list - Small square variant
<Avatar 
  variant="square"
  size="sm"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={<span className="text-xs font-medium">{user.initials}</span>}
/>

Custom Styling

Apply custom styles to match your design system:

<Avatar 
  variant="basic"
  size="lg"
  imageSrc={user.avatar}
  imageAlt={user.name}
  fallback={
    <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-primary-light to-primary text-white font-bold shadow-lg">
      {user.initials}
    </div>
  }
/>

Interactive Avatars

Make avatars interactive with hover effects and click handlers:

<button 
  onClick={() => handleAvatarClick(user.id)}
  className="transition-transform hover:scale-105 focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 rounded-full"
>
  <Avatar 
    variant="ring"
    size="lg"
    imageSrc={user.avatar}
    imageAlt={user.name}
    fallback={
      <div className="flex items-center justify-center w-full h-full bg-gradient-to-br from-primary-light to-primary text-white font-semibold">
        {user.initials}
      </div>
    }
  />
</button>
  • UserMenu: Dropdown menu triggered by avatar clicks
  • UserCard: Card component with avatar and detailed user information
  • TeamList: List component for displaying team members with avatars
  • ProfilePicture: Specialized avatar component for profile pages
  • AvatarGroup: Component for displaying multiple avatars together

API Reference

For the complete API reference and advanced usage patterns, see the Avatar API documentation.

Performance Tips

Image Optimization

  • Use appropriate image sizes (24x24, 32x32, 48x48, 64x64)
  • Implement lazy loading for large avatar lists
  • Use WebP format when possible for better compression

Fallback Strategy

  • Cache user initials to avoid recalculation
  • Use consistent fallback patterns across your app
  • Consider implementing skeleton loaders for better UX

Accessibility

  • Always provide meaningful alt text
  • Test with screen readers
  • Ensure sufficient color contrast in fallback content
  • Use appropriate sizes for different contexts

Variant Selection

  • Choose variants based on context and importance
  • Use consistent variants for similar user types
  • Consider accessibility implications of different variants
Edit this page on GitHub
previousAlert