Avatar

A circular image element with fallback support for representing users. Built on top of Radix UI Avatar primitive with SSR support and enhanced features for grouping multiple avatars.

API Reference

Avatar

Main container component for displaying user avatars.

Props

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply to the avatar
`children`	`ReactNode`	-	`AvatarImage` and `AvatarFallback` components
...props	`ComponentProps<typeof AvatarPrimitive.Root>`	-	All Radix UI Avatar.Root props are supported

AvatarImage

Displays the user's profile image with automatic fallback.

Props

Prop	Type	Default	Description
`src`	`string`	-	Image source URL
`alt`	`string`	-	Alternative text for the image
`className`	`string`	-	Additional CSS classes to apply
...props	`ComponentProps<typeof AvatarPrimitive.Image>`	-	All Radix UI Avatar.Image props are supported

AvatarFallback

Displays fallback content when the image fails to load.

Props

Prop	Type	Default	Description
`className`	`string`	-	Additional CSS classes to apply
`children`	`ReactNode`	-	Fallback content (usually initials)
...props	`ComponentProps<typeof AvatarPrimitive.Fallback>`	-	All Radix UI Avatar.Fallback props are supported

AvatarGroup

Groups multiple avatars in a stacked layout with configurable spacing.

Props

Prop	Type	Default	Description
`children`	`ReactNode`	-	Avatar components to display in the group
`className`	`string`	-	Additional CSS classes to apply
`spacing`	`"tight" \| "normal" \| "loose"`	`"normal"`	Spacing between avatars in the group
`max`	`number`	-	Maximum number of avatars to show before adding a "+N" indicator

Spacing Values

tight: -space-x-1.5 (closer together)
normal: -space-x-1 (default spacing)
loose: -space-x-0.45 (more space between avatars)

Types

interface AvatarGroupProps {
  children: React.ReactNode;
  className?: string;
  spacing?: "tight" | "normal" | "loose";
  max?: number; // Maximum avatars to show before "+N"
}

// Individual Avatar components extend Radix primitives:
// Avatar - ComponentProps<typeof AvatarPrimitive.Root>
// AvatarImage - ComponentProps<typeof AvatarPrimitive.Image>
// AvatarFallback - ComponentProps<typeof AvatarPrimitive.Fallback>

Examples

Basic Avatar

The most basic avatar with image and fallback:

<Avatar>
  <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>

Custom Size

You can customize the size by adding CSS classes:

CNCNCN

<div className="flex items-center gap-4">
  <Avatar className="size-8">
    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
    <AvatarFallback className="text-xs">CN</AvatarFallback>
  </Avatar>
  <Avatar className="size-12">
    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
    <AvatarFallback>CN</AvatarFallback>
  </Avatar>
  <Avatar className="size-16">
    <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
    <AvatarFallback className="text-lg">CN</AvatarFallback>
  </Avatar>
</div>

Avatar Groups with Different Spacing

Tight Spacing

ERLRCN

Normal Spacing

ERLRCN

Loose Spacing

ERLRCN

<div className="flex flex-col gap-6">
  <AvatarGroup spacing="tight">
    <Avatar>
      <AvatarImage src="/images/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
    {/* More avatars... */}
  </AvatarGroup>
  
  <AvatarGroup spacing="normal">
    {/* Avatars with normal spacing */}
  </AvatarGroup>
  
  <AvatarGroup spacing="loose">
    {/* Avatars with loose spacing */}
  </AvatarGroup>
</div>