Skip to main content

Avatar

StorybookView in Storybook

Explore interactive examples and all component variations in our Storybook.

The Avatar component displays user profile images with automatic fallback to initials or icons when images fail to load. Built on Radix UI Avatar primitive for maximum accessibility and reliability.

Basic Usage​

CN

Different Sizes​

CNCNCNCN

Fallback with Icon​

User List​

JS

John Smith

john@example.com

SJ

Sarah Johnson

sarah@example.com

MW

Mike Wilson

mike@example.com

ED

Emma Davis

emma@example.com

Avatar Group​

JSM+2

Avatar with Status​

JS
MS
PC

Properties​

Avatar​

PropertyTypeDescription
classNamestringAdditional CSS classes for the avatar container.

AvatarImage​

PropertyTypeDescription
srcstringURL of the avatar image.
altstringAlternative text for the image.
classNamestringAdditional CSS classes for the image.

AvatarFallback​

PropertyTypeDescription
childrenReactNodeFallback content (initials, icon, etc.).
classNamestringAdditional CSS classes for the fallback.

Features​

Automatic Fallback​

  • If the image fails to load, the fallback is displayed automatically
  • Fallback can contain text (initials) or icons
  • Smooth transition between image and fallback

Accessibility​

  • Full screen reader support
  • Proper alt attributes for images
  • Correct semantic structure
  • ARIA compliance through Radix UI
ContextSizeClasses
Compact list32pxh-8 w-8
Standard list40pxh-10 w-10 (default)
Profile64pxh-16 w-16
Header/Hero80px+h-20 w-20

Common Use Cases​

The Avatar component is perfect for:

  • User profiles - Display user profile pictures in applications
  • Comment systems - Show commenter avatars in discussions
  • Team members - Display team member photos in about pages
  • Contact lists - Show contact photos in messaging apps
  • Author bylines - Display author photos in blog posts
  • User directories - Show user avatars in member listings
  • Navigation bars - Display current user avatar in headers

Best Practices​

  1. Always provide fallback - Use initials or icons when images aren't available
  2. Use appropriate alt text - Describe the user or context of the image
  3. Maintain aspect ratio - Always use square dimensions (same height and width)
  4. Optimize images - Use optimized images of appropriate size
  5. Consider loading states - Implement skeleton or placeholder during loading
  6. Test fallbacks - Verify how the component behaves without images
  7. Accessibility first - Ensure it works well with screen readers