Avatar

An image element with a fallback for representing the user, built on the Base UI Avatar primitive, with initials when the image fails.

TSX
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarImage,
} from "@/components/ui/avatar";

export default function AvatarDemo() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="sm">
        <AvatarFallback>EC</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/logomark.svg" alt="SevenUI" />
        <AvatarFallback>7U</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>JL</AvatarFallback>
        <AvatarBadge aria-label="Online" className="bg-green-500" />
      </Avatar>
    </div>
  );
}

Installation

Bash
Package manager:npmpnpmyarnbun
npx shadcn@latest add @sevenui/avatarpnpm dlx shadcn@latest add @sevenui/avataryarn dlx shadcn@latest add @sevenui/avatarbunx --bun shadcn@latest add @sevenui/avatar

Usage

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

<Avatar>
  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
  <AvatarFallback>CN</AvatarFallback>
</Avatar>;

Examples

Group

AvatarGroup stacks avatars with overlap and background rings; AvatarGroupCount renders the overflow counter. Sizes inside the group follow the avatars’ size.

TSX
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
} from "@/components/ui/avatar";

export default function AvatarGroupDemo() {
  return (
    <AvatarGroup>
      {["EC", "JL", "SR"].map((initials) => (
        <Avatar key={initials}>
          <AvatarFallback>{initials}</AvatarFallback>
        </Avatar>
      ))}
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}

API reference

Avatar

Extends the Base UI Avatar Root — all its props apply.

AvatarImage and AvatarFallback

Extend the Base UI Image and Fallback parts. The image swaps to the fallback on load failure; AvatarFallback accepts a delay prop (ms) to avoid flashing it while the image loads.

AvatarBadge

Extends span. A status dot pinned to the bottom-right corner, sized automatically per avatar size (fits a small icon on default/lg). Color it with className and label it with aria-label.

AvatarGroup and AvatarGroupCount

Structural wrappers extending div — the group overlaps its avatars, the count renders a same-sized circle for the “+N” overflow.