Creative Tim UICreative Tim UI

Shadcn Avatar

PreviousNext

An image element with a fallback for representing a user, typically displayed as a profile picture or user icon.

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarDemo() {
  return (
    <Avatar>
      <AvatarImage
        src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
        alt="profile-picture"
      />
    </Avatar>
  )
}

Installation

pnpm dlx @creative-tim/ui@latest add avatar

Usage

import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
<Avatar>
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>U</AvatarFallback>
</Avatar>

Examples

Avatar Sizes

Avatar components in different sizes (xs, sm, md, lg, xl, xxl) to accommodate various design contexts and spacing requirements.

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarSizes() {
  return (
    <div className="flex items-end gap-2">
      <Avatar className="size-6">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="size-8">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="size-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="size-12">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="size-16">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="size-20">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
    </div>
  )
}

Avatar Variants

Avatar components with different shape variants including circular, rounded, and square, allowing you to choose the style that best matches your design system.

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarVariants() {
  return (
    <div className="flex items-center gap-2">
      <Avatar>
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="rounded-md">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
      <Avatar className="rounded-none">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="profile-picture"
        />
      </Avatar>
    </div>
  )
}

Avatar Stack

Multiple avatar components stacked together with overlapping borders, perfect for displaying groups of users or team members in a compact visual format.

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarStack() {
  return (
    <div className="flex items-center -space-x-4">
      <Avatar className="border-secondary border-2 hover:z-10 focus:z-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="user 1"
        />
      </Avatar>
      <Avatar className="border-secondary border-2 hover:z-10 focus:z-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="user 2"
        />
      </Avatar>
      <Avatar className="border-secondary border-2 hover:z-10 focus:z-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="user 3"
        />
      </Avatar>
      <Avatar className="border-secondary border-2 hover:z-10 focus:z-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="user 4"
        />
      </Avatar>
      <Avatar className="border-secondary border-2 hover:z-10 focus:z-10">
        <AvatarImage
          src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
          alt="user 5"
        />
      </Avatar>
    </div>
  )
}

Avatar With Text

Avatar components paired with text labels showing user names and roles, ideal for user lists, comments, and profile displays where additional context is needed.

Tania Andrew

Web Developer

Tania Andrew

Web Developer

Tania Andrew

Web Developer

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarWithText() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex items-center gap-4">
        <Avatar>
          <AvatarImage
            src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
            alt="avatar"
          />
        </Avatar>
        <div>
          <p className="font-medium">Tania Andrew</p>
          <p className="text-muted-foreground text-sm">Web Developer</p>
        </div>
      </div>
      <div className="flex items-center gap-4">
        <Avatar className="rounded-md">
          <AvatarImage
            src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
            alt="avatar"
          />
        </Avatar>
        <div>
          <p className="font-medium">Tania Andrew</p>
          <p className="text-muted-foreground text-sm">Web Developer</p>
        </div>
      </div>
      <div className="flex items-center gap-4">
        <Avatar className="rounded-none">
          <AvatarImage
            src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
            alt="avatar"
          />
        </Avatar>
        <div>
          <p className="font-medium">Tania Andrew</p>
          <p className="text-muted-foreground text-sm">Web Developer</p>
        </div>
      </div>
    </div>
  )
}

Avatar Custom Styles

An avatar component with custom styling including borders and ring effects, demonstrating how to enhance the visual appearance with additional decorative elements.

import { Avatar, AvatarImage } from "@/components/ui/avatar"

export function AvatarCustomStyles() {
  return (
    <Avatar className="size-12 border border-green-500 ring-4 ring-green-500/20">
      <AvatarImage
        src="https://images.unsplash.com/photo-1750223642533-1b74b17edae8?auto=format&fit=crop&q=80&w=400&h=400"
        alt="avatar"
      />
    </Avatar>
  )
}

Props

The avatar component is built using Radix UI's Avatar primitive and accepts the following props:

Avatar (Root Component)

PropTypeDefaultDescription
classNamestring-Additional CSS classes to apply to the avatar
childrenReactNode-The avatar image and fallback components

AvatarImage

PropTypeDefaultDescription
srcstring-The source URL of the avatar image
altstring-Alternative text for the image (required)
classNamestring-Additional CSS classes to apply to the image

AvatarFallback

PropTypeDefaultDescription
classNamestring-Additional CSS classes to apply to the fallback
childrenReactNode-The fallback content to display when image fails

Best Practices

  • Always provide an alt attribute for accessibility
  • Use AvatarFallback to display initials or a default icon when the image fails to load
  • Choose appropriate sizes based on the context (smaller for lists, larger for profile pages)
  • Maintain consistent sizing within the same component or page
  • Use circular avatars for user profiles and rounded/square for other contexts
  • Ensure avatar images are optimized and properly sized
  • Consider using avatar stacks for displaying multiple users efficiently
  • Provide sufficient contrast between avatar and background
  • Use meaningful fallback content (initials, icons, or default images)

The avatar component provides a flexible and accessible way to display user images with automatic fallback support. It's ideal for user profiles, comments, team displays, navigation menus, and any interface where user representation is needed.