Not FoundElixir UI

Getting Started

Installation

Components

Templates

More

Avatar

Display user profile pictures, initials, or placeholder images in a circular format. Perfect for user interfaces, comment sections, and team member displays.

Installation

Add the Avatar component to your project:

npx @elixir-labs/ui add avatar

Usage

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

export default function MyComponent() {
  return (
    <Avatar>
      <AvatarImage src="/profile.jpg" alt="User" />
      <AvatarFallback>JD</AvatarFallback>
    </Avatar>
  );
}

Examples

Basic Avatar

Avatar
CN
Avatar with image
<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="Avatar" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Avatar Fallback

JD
Avatar with fallback initials
<Avatar>
  <AvatarImage src="/invalid-image.jpg" alt="Avatar" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Avatar Sizes

Small
SM
Small
Default
MD
Default
Large
LG
Large
Extra Large
XL
Extra Large
<Avatar className="h-8 w-8">
  <AvatarImage src="/avatar.jpg" alt="Small" />
  <AvatarFallback className="text-xs">SM</AvatarFallback>
</Avatar>

<Avatar className="h-10 w-10">
  <AvatarImage src="/avatar.jpg" alt="Default" />
  <AvatarFallback>MD</AvatarFallback>
</Avatar>

<Avatar className="h-12 w-12">
  <AvatarImage src="/avatar.jpg" alt="Large" />
  <AvatarFallback>LG</AvatarFallback>
</Avatar>

<Avatar className="h-16 w-16">
  <AvatarImage src="/avatar.jpg" alt="Extra Large" />
  <AvatarFallback className="text-lg">XL</AvatarFallback>
</Avatar>

Avatar Group

User 1
U1
User 2
U2
User 3
U3
+5
<div className="flex -space-x-2">
  <Avatar className="border-2 border-background">
    <AvatarImage src="/user1.jpg" alt="User 1" />
    <AvatarFallback>U1</AvatarFallback>
  </Avatar>
  <Avatar className="border-2 border-background">
    <AvatarImage src="/user2.jpg" alt="User 2" />
    <AvatarFallback>U2</AvatarFallback>
  </Avatar>
  <Avatar className="border-2 border-background">
    <AvatarImage src="/user3.jpg" alt="User 3" />
    <AvatarFallback>U3</AvatarFallback>
  </Avatar>
  <Avatar className="border-2 border-background">
    <AvatarFallback>+5</AvatarFallback>
  </Avatar>
</div>

User Profile Card

John Doe
JD

John Doe

Software Engineer

john.doe@example.com

<div className="flex items-center gap-4 p-4 rounded-lg border">
  <Avatar className="h-12 w-12">
    <AvatarImage src="/john-doe.jpg" alt="John Doe" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <div className="flex-1">
    <h3 className="font-medium">John Doe</h3>
    <p className="text-sm text-muted-foreground">Software Engineer</p>
    <p className="text-xs text-muted-foreground">john.doe@example.com</p>
  </div>
</div>

Team Member List

Alice Johnson
AJ
Alice Johnson
Product Manager
Bob Smith
BS
Bob Smith
Designer
Carol White
CW
Carol White
Developer
const teamMembers = [
  { name: "Alice Johnson", role: "Product Manager", initials: "AJ" },
  { name: "Bob Smith", role: "Designer", initials: "BS" },
  { name: "Carol White", role: "Developer", initials: "CW" },
];

export default function TeamList() {
  return (
    <div className="space-y-3">
      {teamMembers.map((member, index) => (
        <div key={index} className="flex items-center gap-3 p-2 rounded hover:bg-accent">
          <Avatar className="h-8 w-8">
            <AvatarImage src={`/team/${member.name.toLowerCase().replace(' ', '-')}.jpg`} alt={member.name} />
            <AvatarFallback className="text-xs">{member.initials}</AvatarFallback>
          </Avatar>
          <div>
            <div className="font-medium text-sm">{member.name}</div>
            <div className="text-xs text-muted-foreground">{member.role}</div>
          </div>
        </div>
      ))}
    </div>
  );
}

API Reference

Avatar

PropTypeDefaultDescription
classNamestring-Additional CSS classes
childrenReactNode-AvatarImage and AvatarFallback components

AvatarImage

PropTypeDefaultDescription
srcstring-Image source URL
altstring-Alt text for accessibility
classNamestring-Additional CSS classes

AvatarFallback

Displayed when the image fails to load or is not provided. Typically shows user initials.

Source Code

import React from 'react';
import { clsx } from 'clsx';

const Avatar = React.forwardRef(({ className, ...props }, ref) => (
  <div
    ref={ref}
    className={clsx(
      'relative flex h-10 w-10 shrink-0 overflow-hidden rounded-full',
      className
    )}
    {...props}
  />
));
Avatar.displayName = 'Avatar';

const AvatarImage = React.forwardRef(({ className, ...props }, ref) => (
  <img
    ref={ref}
    className={clsx('aspect-square h-full w-full', className)}
    {...props}
  />
));
AvatarImage.displayName = 'AvatarImage';

const AvatarFallback = React.forwardRef(({ className, ...props }, ref) => (
  <div
    ref={ref}
    className={clsx(
      'flex h-full w-full items-center justify-center rounded-full bg-muted',
      className
    )}
    {...props}
  />
));
AvatarFallback.displayName = 'AvatarFallback';

export { Avatar, AvatarImage, AvatarFallback };

Accessibility

The Avatar component follows accessibility guidelines:

  • Always provide meaningful alt text for avatar images
  • Fallback content is accessible to screen readers
  • Proper semantic structure with img elements
  • Works well with keyboard navigation
  • Maintains proper contrast ratios for fallback text

Best Practices

✅ Do

  • Use meaningful fallback text (initials or icons)
  • Provide descriptive alt text for images
  • Optimize images for different screen densities
  • Use consistent sizing across your application
  • Consider loading states for slow network connections

❌ Don't

  • Leave empty fallbacks without any content
  • Use overly large images without optimization
  • Forget to handle image loading errors
  • Make avatars too small to be easily clickable on touch devices

💡 Pro Tip

For better performance, consider using optimized image formats like WebP and provide multiple sizes for different use cases. You can also implement lazy loading for avatar lists.