Avatar

Examples

Overview

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

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

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

Always include an AvatarFallback alongside AvatarImage to handle loading states and broken images. AvatarFallback truncates string children to a single character, so pass the first initial only.

Usage

Variants

Use variant="primary" (the default) for branded fallbacks: the active user, Rogo-owned entities, anywhere you want the avatar to feel "ours". Use variant="secondary" for neutral cases where colour would compete with surrounding UI: overflow chips, low-emphasis lists, or contexts where the avatar is decorative rather than identifying.

For team / category colours, reach for the decorative variants: green, blue, olive, crimson. They share a text-neutral-300 foreground so initials stay legible across all four hues.

<Avatar>
  <AvatarFallback>J</AvatarFallback>
</Avatar>

<Avatar variant="secondary">
  <AvatarFallback>3</AvatarFallback>
</Avatar>

<Avatar variant="green">
  <AvatarFallback>A</AvatarFallback>
</Avatar>

Sizes

<Avatar size="lg">
  <AvatarFallback>J</AvatarFallback>
</Avatar>

Stacked groups

Use AvatarStack. It handles overlap, the per-position mask cutouts, and the hover interaction (lift to z-20, drop self-mask, push the next sibling's left-cutout in) automatically.

import { Avatar, AvatarFallback, AvatarOverflow, AvatarStack } from "@rogo-technologies/ui/avatar";

<AvatarStack size="lg">
  <Avatar tooltip="Alice Brown" variant="green">
    <AvatarFallback>A</AvatarFallback>
  </Avatar>
  <Avatar tooltip="Carla Diaz" variant="blue">
    <AvatarFallback>C</AvatarFallback>
  </Avatar>
  <AvatarOverflow tooltip="3 more people">+3</AvatarOverflow>
</AvatarStack>;

AvatarStack enforces a single size for all children, and the last entry is treated specially: it only gains a left-cutout when its predecessor is hovered, never a right-cutout, since it has no neighbour on the right.

The stack applies those cutouts by cloning size and className onto each child. A child that is its own component must accept both and pass them through to the Avatar it renders, or its faces overlap with no cutout at all.

Overflow chip

For "+N more" counters or any non-initial string that needs to sit in a stack, use AvatarOverflow. It shares Avatar's circular geometry and size scale so masks line up, but renders in font-sans on bg-tertiary / text-tertiary to read as a neutral count rather than a person. Multi-character strings are not truncated.

<AvatarStack size="lg">
  <Avatar variant="green">
    <AvatarFallback>A</AvatarFallback>
  </Avatar>
  <AvatarOverflow tooltip="3 more people">+3</AvatarOverflow>
</AvatarStack>

Generating initials

function getInitial(name: string): string {
  return name.trim().charAt(0).toUpperCase();
}

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

Tooltip

Pass a tooltip prop (string or React node) and the avatar wires up a default Tooltip out of the box, with no need to compose Tooltip / TooltipTrigger / TooltipContent by hand. Useful in stacks where each face needs its own name on hover.

<Avatar tooltip="Jane Doe">
  <AvatarFallback>J</AvatarFallback>
</Avatar>

<Avatar tooltip={<span>Alex Brown<br/>alex@example.com</span>}>
  <AvatarFallback>A</AvatarFallback>
</Avatar>

tooltipDelay sets the hover delay in ms. Use 0 where the tooltip carries the avatar's only label, since a bare name is not worth making the reader wait for, and the delay reads as lag when the face is the thing being pointed at.

<Avatar tooltip="Jane Doe" tooltipDelay={0}>
  <AvatarFallback>J</AvatarFallback>
</Avatar>

For richer behaviour (custom side, controlled open state), compose Tooltip manually instead of using this prop.

Custom render

Render the avatar as a link or other element with render.

import Link from "next/link";

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

Accessibility

• Always provide meaningful alt text for AvatarImage
• When using icons as fallback, give them an aria-label
• Avatar groups should use aria-label to describe the group

API

Avatar

AvatarImage

AvatarStack

AvatarFallback

AvatarOverflow

Guidelines

Do

• Always include AvatarFallback when using AvatarImage
• Use the first initial of the name for fallbacks, since the component truncates strings to one character
• Use consistent sizes within the same context
• Use a mask-image cutout (not a ring) when stacking avatars so the separation is surface-agnostic
• Use size="xl" or size="lg" for profile headers and hero sections
• Reach for decorative variants (green / blue / olive / crimson) for team or category colour instead of overriding className with raw Tailwind colours

Don't

• Don't pass multi-character strings expecting them to render, because AvatarFallback slices to one character
• Don't use size="xs" for standalone avatars, since it's too small to be meaningful
• Don't forget alt text for images
• Don't mix different sizes in the same avatar group
• Don't rely solely on the avatar to convey identity, and pair it with a name when possible