Avatar

The Avatar component is designed for displaying user profile images with automatic fallback support. When an image fails to load or is not provided, it gracefully displays fallback text. The component supports multiple sizes and can be customized with different color schemes.

Description

A circular avatar component that displays profile images with fallback text support and multiple size options.

Usage

import { Avatar } from "@crafted-ui/react";

<Avatar src="https://github.com/username.png" fallback="JD" />

Props

The Avatar component accepts the following props:

Prop	Type	Default	Description
size	’sm’ | ‘md’ | ‘lg’ | ‘xl'	'md’	Sets the avatar’s size
fallback	string	undefined	Text to display when image is not available
src	string	undefined	Source URL for the avatar image
height	string	undefined	Custom height for the image
width	string	undefined	Custom width for the image
imgClassName	string	undefined	Additional CSS class names for the image
className	string	undefined	Additional CSS class names for the container
children	ReactNode	undefined	Custom content inside the avatar

The component also accepts all standard HTML div attributes.

Available Sizes

The Avatar component comes in four predefined sizes to fit different contexts.

<Avatar size="sm" fallback="SM" src="https://github.com/username.png" />
<Avatar size="md" fallback="MD" src="https://github.com/username.png" />
<Avatar size="lg" fallback="LG" src="https://github.com/username.png" />
<Avatar size="xl" fallback="XL" src="https://github.com/username.png" />

Size	Dimensions	Use Case
sm	40x40px	Small lists, comments
md	48x48px	Default size, general use
lg	56x56px	Profile cards, larger lists
xl	64x64px	Profile headers, main displays

With Images

When a valid image source is provided, the avatar displays the image.

<Avatar src="https://github.com/username.png" fallback="NM" />
<Avatar src="https://github.com/username.png" fallback="JD" size="lg" />

Fallback Text Only

When no image is provided or the image fails to load, the fallback text is displayed.

<Avatar fallback="JD" />
<Avatar fallback="SM" size="sm" />
<Avatar fallback="LG" size="lg" />
<Avatar fallback="XL" size="xl" />

Color Variants

Use the className prop to apply custom color schemes that match your design system.

<Avatar fallback="A" />
<Avatar fallback="B" className="bg-destructive text-destructive-foreground" />
<Avatar fallback="C" className="bg-secondary text-secondary-foreground" />
<Avatar fallback="D" className="bg-accent text-accent-foreground" />
<Avatar fallback="E" className="bg-muted text-muted-foreground" />

Custom Image Styling

Use the imgClassName prop to style the image element specifically.

<Avatar 
  src="https://github.com/username.png" 
  fallback="A" 
  imgClassName="grayscale" 
/>
<Avatar 
  src="https://github.com/username.png" 
  fallback="B" 
  imgClassName="sepia" 
/>

The Avatar component follows accessibility best practices:

• Uses semantic HTML structure with proper image elements
• Provides fallback content when images are unavailable
• Maintains proper color contrast ratios in default states
• Uses alt="" for decorative avatar images (since context is provided by surrounding content)

When implementing avatars, consider:

1. Context: Ensure the avatar’s purpose is clear from surrounding content
2. Fallback: Always provide meaningful fallback text (initials, first letter of name)
3. Contrast: Verify color combinations meet accessibility standards
4. Size: Choose appropriate sizes for the context and viewing distance

Basic Avatar with Image

<Avatar 
  src="https://github.com/username.png" 
  fallback="JD" 
/>

Avatar with Custom Size

<Avatar 
  src="https://github.com/username.png" 
  fallback="JD" 
  size="lg"
/>

Avatar Group

<div className="flex -space-x-2">
  <Avatar src="https://github.com/user1.png" fallback="U1" />
  <Avatar src="https://github.com/user2.png" fallback="U2" />
  <Avatar src="https://github.com/user3.png" fallback="U3" />
  <Avatar fallback="+5" className="bg-muted text-muted-foreground" />
</div>

Avatar with Status Indicator

<div className="relative">
  <Avatar src="https://github.com/username.png" fallback="JD" />
  <span className="absolute bottom-0 right-0 h-3 w-3 rounded-full bg-green-500 ring-2 ring-white"></span>
</div>

Custom Content Avatar

<Avatar>
  <svg className="h-6 w-6" fill="currentColor" viewBox="0 0 20 20">
    <path fillRule="evenodd" d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z" clipRule="evenodd" />
  </svg>
</Avatar>