Avatar

Import

import { Avatar, AvatarFallback, AvatarImage } from "@timelycare/helix-ui"

Props

interface AvatarProps {
  className?: string
  children: React.ReactNode
}

interface AvatarImageProps {
  src: string
  alt: string
  className?: string
  onLoadingStatusChange?: (status: "loading" | "loaded" | "error") => void
}

interface AvatarFallbackProps {
  className?: string
  children: React.ReactNode  // Typically 1-2 character initials
  delayMs?: number           // Delay before showing fallback
}

Variants

Shapes

Rounded Shape Radius by Size

Sizes

Styling

Fallback

Fallback Text Size by Avatar Size

Image Loading State

States

Focus State by Size

Focus ring color: ring (#a1a1aa) border with rgba(163,163,163,0.5) shadow. Simplified implementation uses ring-3 ring-ring for consistent focus styling.

Common Patterns

Basic with Fallback (Rounded — default)

<Avatar className="rounded-2xl">
  <AvatarImage src="/user.jpg" alt="@username" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Rounded Shape — All Sizes (size-dependent radius)

// Size 12 — rounded-2xl (16px)
<Avatar className="rounded-2xl">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

// Size 10 — rounded-xl (14px)
<Avatar className="size-10 rounded-xl">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

// Size 8 — rounded-lg (10px)
<Avatar className="size-8 rounded-lg">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-sm">CN</AvatarFallback>
</Avatar>

// Size 6 — rounded-md (8px)
<Avatar className="size-6 rounded-md">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-xs">CN</AvatarFallback>
</Avatar>

// Size 5 — rounded-sm (6px)
<Avatar className="size-5 rounded-sm">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-xs">CN</AvatarFallback>
</Avatar>

Circle Shape — All Sizes

// Large (48px)
<Avatar className="size-12">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

// Default (32px)
<Avatar className="size-8">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-sm">CN</AvatarFallback>
</Avatar>

// Small (24px)
<Avatar className="size-6">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-xs">CN</AvatarFallback>
</Avatar>

// Extra small (20px)
<Avatar className="size-5">
  <AvatarImage src="/user.jpg" />
  <AvatarFallback className="text-xs">CN</AvatarFallback>
</Avatar>

Fallback with Border

<Avatar>
  <AvatarFallback className="bg-accent text-accent-foreground border border-accent-border">
    CN
  </AvatarFallback>
</Avatar>

Avatar Group (Stacked)

<div className="flex items-center pr-2">
  <Avatar className="size-12 border-2 border-background -mr-2">
    <AvatarImage src="/user1.jpg" />
    <AvatarFallback>U1</AvatarFallback>
  </Avatar>
  <Avatar className="size-12 border-2 border-background -mr-2">
    <AvatarImage src="/user2.jpg" />
    <AvatarFallback>U2</AvatarFallback>
  </Avatar>
  <Avatar className="size-12 border-2 border-background -mr-2">
    <AvatarFallback className="bg-accent text-accent-foreground border border-accent-border">
      +3
    </AvatarFallback>
  </Avatar>
</div>

With User Info

<div className="flex items-center gap-3">
  <Avatar>
    <AvatarImage src="/user.jpg" />
    <AvatarFallback>JD</AvatarFallback>
  </Avatar>
  <div>
    <p className="text-sm font-medium">John Doe</p>
    <p className="text-xs text-muted-foreground">john@example.com</p>
  </div>
</div>

Component Structure

{/* Rounded shape variant — size 12 (default) */}
<div className="relative size-12 overflow-hidden rounded-2xl">
  
  {/* AvatarImage */}
  <img 
    src="/user.jpg" 
    alt="User" 
    className="absolute inset-0 size-full object-cover" 
  />
  
  {/* AvatarFallback (shown when image fails/loading) */}
  <div className="absolute inset-0 flex items-center justify-center bg-accent border border-accent-border text-sm text-accent-foreground">
    CN
  </div>
  
</div>

{/* Rounded shape variant — size 10 */}
<div className="relative size-10 overflow-hidden rounded-xl">
  ...
</div>

{/* Rounded shape variant — size 8 */}
<div className="relative size-8 overflow-hidden rounded-lg">
  ...
</div>

{/* Rounded shape variant — size 6 */}
<div className="relative size-6 overflow-hidden rounded-md">
  ...
</div>

{/* Rounded shape variant — size 5 */}
<div className="relative size-5 overflow-hidden rounded-sm">
  ...
</div>

{/* Circle shape variant */}
<div className="relative size-12 overflow-hidden rounded-full">
  ...
</div>

Accessibility

• Built on Radix Avatar — presentational component
• Provide meaningful alt text on AvatarImage
• Fallback text is announced by screen readers
• No keyboard interaction (non-interactive element)

Gotchas

See Also

• Related Components: Hover Card (profile preview on hover), Badge (status indicator)
• Tokens: Colors — Theme-aware color tokens

Last updated: February 20, 2026