For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Avatar

A circular user image with fallback, badge, and stacking group.

Web
Frakment
MER
ANSALV
+3
avatar.tsx
"use client";

import * as React from "react";

import { cn } from "@/lib/utils";

type ImageLoadingStatus = "idle" | "loading" | "loaded" | "error";

function useImageLoadingStatus(
  src: string | undefined,
  referrerPolicy: React.HTMLAttributeReferrerPolicy | undefined
): ImageLoadingStatus {
  const [status, setStatus] = React.useState<ImageLoadingStatus>("idle");

  React.useEffect(() => {
    if (!src) {
      setStatus("error");
      return;
    }
    let isMounted = true;
    const image = new window.Image();
    const update = (next: ImageLoadingStatus) => () => {
      if (isMounted) {
        setStatus(next);
      }
    };
    setStatus("loading");
    image.onload = update("loaded");
    image.onerror = update("error");
    if (referrerPolicy) {
      image.referrerPolicy = referrerPolicy;
    }
    image.src = src;
    return () => {
      isMounted = false;
    };
  }, [src, referrerPolicy]);

  return status;
}

interface AvatarContextValue {
  imageLoadingStatus: ImageLoadingStatus;
  onImageLoadingStatusChange: (status: ImageLoadingStatus) => void;
}

const AvatarContext = React.createContext<AvatarContextValue | null>(null);

function useAvatarContext(component: string): AvatarContextValue {
  const ctx = React.useContext(AvatarContext);
  if (!ctx) {
    throw new Error(`${component} must be used within Avatar`);
  }
  return ctx;
}

type AvatarProps = React.ComponentProps<"span"> & {
  size?: "default" | "sm" | "lg";
};

function Avatar({
  className,
  size = "default",
  children,
  ...props
}: AvatarProps) {
  const [imageLoadingStatus, setImageLoadingStatus] =
    React.useState<ImageLoadingStatus>("idle");
  const ctxValue = React.useMemo<AvatarContextValue>(
    () => ({
      imageLoadingStatus,
      onImageLoadingStatusChange: setImageLoadingStatus,
    }),
    [imageLoadingStatus]
  );
  return (
    <AvatarContext.Provider value={ctxValue}>
      <span
        className={cn(
          "group/avatar after:border-border relative flex size-8 shrink-0 rounded-full select-none after:absolute after:inset-0 after:rounded-full after:border after:mix-blend-darken data-[size=lg]:size-10 data-[size=sm]:size-6 dark:after:mix-blend-lighten",
          className
        )}
        data-size={size}
        data-slot="avatar"
        {...props}
      >
        {children}
      </span>
    </AvatarContext.Provider>
  );
}

type AvatarImageProps = React.ComponentProps<"img"> & {
  onLoadingStatusChange?: (status: ImageLoadingStatus) => void;
};

function AvatarImage({
  alt,
  className,
  onLoadingStatusChange,
  referrerPolicy,
  src,
  ...props
}: AvatarImageProps) {
  const { onImageLoadingStatusChange } = useAvatarContext("AvatarImage");
  const isStringSrc = typeof src === "string";
  const imageLoadingStatus = useImageLoadingStatus(
    isStringSrc ? src : undefined,
    referrerPolicy
  );

  React.useEffect(() => {
    onImageLoadingStatusChange(imageLoadingStatus);
  }, [imageLoadingStatus, onImageLoadingStatusChange]);

  React.useEffect(() => {
    onLoadingStatusChange?.(imageLoadingStatus);
  }, [imageLoadingStatus, onLoadingStatusChange]);

  if (isStringSrc && imageLoadingStatus !== "loaded") {
    return null;
  }

  return (
    <img
      alt={alt}
      className={cn(
        "aspect-square size-full rounded-full object-cover",
        className
      )}
      data-slot="avatar-image"
      referrerPolicy={referrerPolicy}
      src={src}
      {...props}
    />
  );
}

function AvatarFallback({ className, ...props }: React.ComponentProps<"span">) {
  const { imageLoadingStatus } = useAvatarContext("AvatarFallback");
  if (imageLoadingStatus === "loaded") {
    return null;
  }
  return (
    <span
      className={cn(
        "bg-muted text-muted-foreground data-[status=error]:bg-destructive flex size-full items-center justify-center rounded-full text-sm group-data-[size=sm]/avatar:text-xs data-[status=error]:text-white",
        className
      )}
      data-slot="avatar-fallback"
      data-status={imageLoadingStatus}
      {...props}
    />
  );
}

function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
  return (
    <span
      className={cn(
        "bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none",
        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
        className
      )}
      data-slot="avatar-badge"
      {...props}
    />
  );
}

function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn(
        "group/avatar-group *:data-[slot=avatar]:ring-background flex -space-x-2 *:data-[slot=avatar]:ring-2",
        className
      )}
      data-slot="avatar-group"
      {...props}
    />
  );
}

function AvatarGroupCount({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      className={cn(
        "bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 items-center justify-center rounded-full text-sm ring-2 group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
        className
      )}
      data-slot="avatar-group-count"
      {...props}
    />
  );
}

export {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
  type AvatarImageProps,
};

Avatar renders a circular user image with a text fallback when the image fails to load or is missing. A small composable API covers badges, groups, and counts.

Installation

Usage

avatar.tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
avatar.tsx
<Avatar>
  <AvatarImage src="/avatars/me.avif" />
  <AvatarFallback>ME</AvatarFallback>
</Avatar>

Pass grayscale through className to desaturate. Demo assets follow a -l (facing left) and -r (facing right) convention — pick one per row.

Group

AvatarGroup overlaps avatars with a 2px background ring between each one, keeping the stack readable. Place AvatarGroupCount as the last child to show how many more are hidden, and AvatarBadge inside an Avatar to indicate presence. Swap to right-to-left stacking with className="flex-row-reverse".

ANSALV
avatar-group.tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarImage,
} from "@/components/ui/avatar";

export function AvatarGroupDemo() {
  return (
    <AvatarGroup aria-label="3 participants">
      <Avatar>
        <AvatarImage src="/avatars/female-l-1.avif" />
        <AvatarFallback>AN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/female-l-2.avif" />
        <AvatarFallback>SA</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/female-l-3.avif" />
        <AvatarFallback>LV</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  );
}

With count

ANSALVMX
+3
avatar-count.tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar";

export function AvatarCount() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="/avatars/female-l-1.avif" />
        <AvatarFallback>AN</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/female-l-2.avif" />
        <AvatarFallback>SA</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/female-l-3.avif" />
        <AvatarFallback>LV</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/male-l.avif" />
        <AvatarFallback>MX</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}
avatargroup.tsx
<AvatarGroup>
  <Avatar>
    <AvatarImage src="/avatars/anna.avif" />
    <AvatarFallback>AN</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/avatars/sara.avif" />
    <AvatarFallback>SA</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/avatars/liv.avif" />
    <AvatarFallback>LV</AvatarFallback>
  </Avatar>
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>

With badge

Place AvatarBadge as the last child of an Avatar. Its position is automatic (bottom-right). Put the status in sr-only text inside the badge so screen readers announce it.

ANOnlineSAAwayMX
+5
avatar-badge-group.tsx
import {
  Avatar,
  AvatarBadge,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar";

export function AvatarBadgeGroup() {
  return (
    <AvatarGroup>
      <Avatar>
        <AvatarImage src="/avatars/female-l-1.avif" />
        <AvatarFallback>AN</AvatarFallback>
        <AvatarBadge className="bg-green-600 dark:bg-green-800">
          <span className="sr-only">Online</span>
        </AvatarBadge>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/female-l-2.avif" />
        <AvatarFallback>SA</AvatarFallback>
        <AvatarBadge className="bg-yellow-500 dark:bg-yellow-700">
          <span className="sr-only">Away</span>
        </AvatarBadge>
      </Avatar>
      <Avatar>
        <AvatarImage src="/avatars/male-l.avif" />
        <AvatarFallback>MX</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+5</AvatarGroupCount>
    </AvatarGroup>
  );
}

With image and fallback

Pass src on AvatarImage. AvatarFallback renders while the image loads, when it fails, or when no image is supplied. A failed load auto-styles the fallback with the destructive token. Without AvatarImage, the fallback keeps the muted surface.

ANSALV
ANSALV
JDAI?
avatar-image-fallback.tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarImage,
} from "@/components/ui/avatar";

export function AvatarImageFallback() {
  return (
    <div className="flex flex-row flex-wrap items-center gap-6">
      <AvatarGroup>
        <Avatar>
          <AvatarImage src="/avatars/female-l-1.avif" />
          <AvatarFallback>AN</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/female-l-2.avif" />
          <AvatarFallback>SA</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/female-l-3.avif" />
          <AvatarFallback>LV</AvatarFallback>
        </Avatar>
      </AvatarGroup>
      <AvatarGroup>
        <Avatar>
          <AvatarImage src="/avatars/missing-a.avif" />
          <AvatarFallback>AN</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/missing-b.avif" />
          <AvatarFallback>SA</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/missing-c.avif" />
          <AvatarFallback>LV</AvatarFallback>
        </Avatar>
      </AvatarGroup>
      <AvatarGroup>
        <Avatar>
          <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarFallback>AI</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarFallback>?</AvatarFallback>
        </Avatar>
      </AvatarGroup>
    </div>
  );
}

Sizes

Three sizes are available via the size prop. The default is 32px, sm is 24px, lg is 40px. Pass size on each Avatar in a group and the trailing AvatarGroupCount follows.

ANSALV
+3
ANSALV
+3
ANSALV
+3
avatar-sizes.tsx
import {
  Avatar,
  AvatarFallback,
  AvatarGroup,
  AvatarGroupCount,
  AvatarImage,
} from "@/components/ui/avatar";

export function AvatarSizes() {
  return (
    <div className="flex flex-row flex-wrap items-center gap-6">
      <AvatarGroup>
        <Avatar size="sm">
          <AvatarImage src="/avatars/female-l-1.avif" />
          <AvatarFallback>AN</AvatarFallback>
        </Avatar>
        <Avatar size="sm">
          <AvatarImage src="/avatars/female-l-2.avif" />
          <AvatarFallback>SA</AvatarFallback>
        </Avatar>
        <Avatar size="sm">
          <AvatarImage src="/avatars/female-l-3.avif" />
          <AvatarFallback>LV</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
      <AvatarGroup>
        <Avatar>
          <AvatarImage src="/avatars/female-l-1.avif" />
          <AvatarFallback>AN</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/female-l-2.avif" />
          <AvatarFallback>SA</AvatarFallback>
        </Avatar>
        <Avatar>
          <AvatarImage src="/avatars/female-l-3.avif" />
          <AvatarFallback>LV</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
      <AvatarGroup>
        <Avatar size="lg">
          <AvatarImage src="/avatars/female-l-1.avif" />
          <AvatarFallback>AN</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarImage src="/avatars/female-l-2.avif" />
          <AvatarFallback>SA</AvatarFallback>
        </Avatar>
        <Avatar size="lg">
          <AvatarImage src="/avatars/female-l-3.avif" />
          <AvatarFallback>LV</AvatarFallback>
        </Avatar>
        <AvatarGroupCount>+3</AvatarGroupCount>
      </AvatarGroup>
    </div>
  );
}

In context

Pair Avatar with Message and Bubble for a chat layout.

R
Assistant
Reading your build log now.
ME
Thanks!
avatar-context.tsx
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import {
  Bubble,
  BubbleContent,
  Message,
  MessageAvatar,
  MessageContent,
  MessageHeader,
} from "@/components/ui/message";

export function AvatarContext() {
  return (
    <div className="w-full max-w-md space-y-3 p-6">
      <Message>
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/male-r.avif" />
            <AvatarFallback>R</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <MessageHeader>Assistant</MessageHeader>
          <Bubble>
            <BubbleContent>Reading your build log now.</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
      <Message align="end">
        <MessageAvatar>
          <Avatar>
            <AvatarImage src="/avatars/female-l-1.avif" />
            <AvatarFallback>ME</AvatarFallback>
          </Avatar>
        </MessageAvatar>
        <MessageContent>
          <Bubble align="end" variant="muted">
            <BubbleContent>Thanks!</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    </div>
  );
}

API Reference

Avatar

PropTypeDefaultDescription
size
smdefaultlg
defaultControls the diameter of the avatar (24px / 32px / 40px).

AvatarImage

Renders the avatar image. Requires src and alt. Applies object-cover and rounded-full. Hidden until the image finishes loading, so the fallback shows first.

AvatarFallback

Renders children when the image is missing, still loading, or fails. Use 2–3 character initials.

AvatarBadge

Extends React.ComponentProps<"span">. Positioned absolutely at the bottom-right. Pass a background color with className (e.g., bg-green-600).

AvatarGroup / AvatarGroupCount

Extend React.ComponentProps<"div">. Group applies -space-x-2 and a 2px background ring per avatar. Count inherits the size of the group's avatars via has-data-[size=lg].

Accessibility

  • Always pass alt on AvatarImage — describe the person, not the file. Use @username for handles.
  • AvatarFallback initials act as a visual label but are not read as a name. If the avatar has semantic meaning, wrap the group in a container with aria-label.
  • AvatarBadge is decorative. Convey the status in text when it matters (e.g., "Online").
  • AvatarGroup should have an accessible label like aria-label="3 participants" when it summarizes a list.

Best Practices

  • Always include a fallback. AvatarFallback renders when the image fails or is missing.
  • Size by context. 24px in lists, 40px in headers, 64px in profiles.
  • Add an accessible name. Wrap in a button with aria-label when clickable.
  • Do not rely on the image alone. Pair with the user's name or a tooltip.