Avatar

Overview

The Avatar component displays a user's profile image with automatic fallback to initials or icons when no image is available. It's built with three composable parts: Avatar (root), AvatarImage, and AvatarFallback.

import { Avatar, AvatarImage, AvatarFallback } from "@rogo-technologies/ui/avatar"

<Avatar>
  <AvatarImage src="/path/to/image.jpg" alt="User name" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Sizes

Use the size prop to control avatar dimensions. The default size is md.

<Avatar size="xs"><AvatarFallback>XS</AvatarFallback></Avatar>
<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>
<Avatar size="2xl"><AvatarFallback>2X</AvatarFallback></Avatar>

With Image

Use AvatarImage to display a user's profile photo. The image automatically fills the circular avatar container.

<Avatar size="lg">
  <AvatarImage src="https://example.com/avatar.jpg" alt="John Doe" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Always include an AvatarFallback alongside AvatarImage to handle loading states and broken images gracefully.

Fallback

Use AvatarFallback to display initials, icons, or placeholder content when no image is available or while the image loads.

With Initials

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Avatar Groups

Display multiple avatars in a stack for teams or collaborators.

<div className="flex -space-x-1.5">
  <Avatar className="ring-2 ring-white">
    <AvatarImage src="/user1.jpg" alt="User 1" />
    <AvatarFallback>U1</AvatarFallback>
  </Avatar>
  <Avatar className="ring-2 ring-white">
    <AvatarImage src="/user2.jpg" alt="User 2" />
    <AvatarFallback>U2</AvatarFallback>
  </Avatar>
  <Avatar className="ring-2 ring-white">
    <AvatarFallback>+3</AvatarFallback>
  </Avatar>
</div>

With Custom Render

Use the render prop to render the avatar as a different element, such as a link.

import Link from "next/link"

<Avatar render={<Link href="/profile" />}>
  <AvatarImage src="/avatar.jpg" alt="Profile" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Generating Initials

A common pattern is to generate initials from a user's name:

function getInitials(name: string): string {
  return name
    .split(" ")
    .map((part) => part[0])
    .join("")
    .toUpperCase()
    .slice(0, 2)
}

<Avatar>
  <AvatarImage src={user.avatar} alt={user.name} />
  <AvatarFallback>{getInitials(user.name)}</AvatarFallback>
</Avatar>

Props

Avatar

The root container component.

AvatarImage

The image component that displays the user's photo.

AvatarFallback

The fallback content shown when no image is available.

Accessibility

• Always provide meaningful alt text for AvatarImage
• When using icons as fallback, ensure they have appropriate aria-label
• Avatar groups should use aria-label to describe the group

<Avatar aria-label="John Doe's profile picture">
  <AvatarImage src="/avatar.jpg" alt="John Doe" />
  <AvatarFallback aria-hidden="true">JD</AvatarFallback>
</Avatar>

Usage Guidelines

Do

• Always include AvatarFallback when using AvatarImage
• Use meaningful initials (first + last name) for fallbacks
• Use consistent sizes within the same context
• Add a ring/border when stacking avatars to create visual separation
• Use size="xl" or size="lg" for profile headers and hero sections

Don't

• Don't use more than 2 characters for initials—they won't fit well
• Don't use size="xs" for standalone avatars—it's too small to be meaningful
• Don't forget alt text for images—it's required for accessibility
• Don't mix different sizes in the same avatar group
• Don't rely solely on the avatar to convey identity—pair with a name when possible