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

Code

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

Sizes

Four size options are available to suit different layout contexts.

SMMDLGXL

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.

ABCD

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

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>
  );
}

Badge - Status indicator labels
DataCard - Metric display card
ProductCard - Product display card

Avatar

On this page