Skip to content
Nim UI

Avatar

The Avatar component displays a user’s profile image with graceful fallback to initials or placeholder content. Built on top of Radix UI Avatar for robust image loading and fallback behavior.

Import

import { Avatar, AvatarImage, AvatarFallback } from '@nim-ui/components';

Basic Usage

Avatar with Image and Fallback

JD
View Code 
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Sizes

Four size options are available to suit different layout contexts.

Avatar Sizes

SMMDLGXL
View Code 
<Avatar size="sm">
  <AvatarFallback>SM</AvatarFallback>
</Avatar>
<Avatar size="md">
  <AvatarFallback>MD</AvatarFallback>
</Avatar>
<Avatar size="lg">
  <AvatarFallback>LG</AvatarFallback>
</Avatar>
<Avatar size="xl">
  <AvatarFallback>XL</AvatarFallback>
</Avatar>

Fallback

When the image fails to load or no src is provided, the AvatarFallback content is displayed automatically.

Fallback Avatars

ABCD
View Code 
{/* Image fails to load, fallback is shown */}
<Avatar>
  <AvatarImage src="/broken-image.jpg" alt="User" />
  <AvatarFallback>AB</AvatarFallback>
</Avatar>


{/* No image, fallback only */}
<Avatar size="lg">
  <AvatarFallback>CD</AvatarFallback>
</Avatar>

Props

Avatar

Name Type Default Description
size 'sm' | 'md' | 'lg' | 'xl' 'md' Size of the avatar
className string - Additional CSS classes to apply
children * ReactNode - AvatarImage and AvatarFallback components

AvatarImage

Name Type Default Description
src * string - URL of the avatar image
alt * string - Alt text for the image
className string - Additional CSS classes to apply

AvatarFallback

Name Type Default Description
children * ReactNode - Fallback content, typically 1-2 character initials
className string - Additional CSS classes to apply

Usage Examples

User Profile Header

function UserProfile({ user }: { user: User }) {
  const initials = user.name
    .split(' ')
    .map((n) => n[0])
    .join('')
    .toUpperCase();


  return (
    <div className="flex items-center gap-3">
      <Avatar size="lg">
        <AvatarImage src={user.avatarUrl} alt={user.name} />
        <AvatarFallback>{initials}</AvatarFallback>
      </Avatar>
      <div>
        <p className="font-semibold">{user.name}</p>
        <p className="text-sm text-neutral-500">{user.email}</p>
      </div>
    </div>
  );
}

Avatar Group

function AvatarGroup({ users }: { users: User[] }) {
  return (
    <div className="flex -space-x-2">
      {users.slice(0, 4).map((user) => (
        <Avatar key={user.id} size="sm" className="ring-2 ring-white">
          <AvatarImage src={user.avatarUrl} alt={user.name} />
          <AvatarFallback>{user.initials}</AvatarFallback>
        </Avatar>
      ))}
      {users.length > 4 && (
        <Avatar size="sm" className="ring-2 ring-white">
          <AvatarFallback>+{users.length - 4}</AvatarFallback>
        </Avatar>
      )}
    </div>
  );
}