Base

Avatar

Avatar displays a profile image when available and automatically falls back to initials derived from `name`, or to `children` when provided.

Installation

npx shadcn add https://rck.vibeboxph.com//r/avatar.json

Live preview & controls

Controls

<Avatar name="Demo user" src="/avatar.png" />

Anatomy

AvatarThe circular container, image, and initials fallback.

Props

Prop	Type	Default	Description
name*	string	—	Person's name — drives auto initials and default image alt text.
src	string	—	Profile image URL. When missing or broken, initials or children are shown.
alt	string	—	Image alt text. Defaults to `name`.
className	string	—	Size and shape overrides via Tailwind (default `size-10`).
children	ReactNode	—	Optional fallback override when the image is unavailable.

Accessibility

Image alt text defaults to `name` — override with `alt` when needed.
Fallback initials are visible text — ensure they uniquely identify the user in context.
Decorative avatar stacks should mark redundant images `alt=""` and rely on adjacent visible names.

Source

registry/rck/ui/avatar.tsx

"use client";

import * as React from "react";
import * as AvatarPrimitive from "@/registry/rck/primitives/avatar";
import { cn, getInitials } from "@/lib/utils";

export interface AvatarProps extends React.HTMLAttributes<HTMLSpanElement> {
  /** Person's name — drives auto initials and default image alt text. */
  name: string;
  /** Profile image URL. When missing or broken, initials or children are shown. */
  src?: string;
  /** Image alt text. Defaults to `name`. */
  alt?: string;
}

export const Avatar = React.forwardRef<HTMLSpanElement, AvatarProps>(
  ({ className, name, src, alt, children, ...props }, ref) => {
    const [loaded, setLoaded] = React.useState(false);
    const [failed, setFailed] = React.useState(false);

    React.useEffect(() => {
      setLoaded(false);
      setFailed(false);
    }, [src]);

    const showImage = Boolean(src) && loaded && !failed;
    const fallbackContent = children ?? getInitials(name);

    return (
      <AvatarPrimitive.Root
        ref={ref}
        data-slot="avatar"
        className={cn(
          "bg-surface-2 relative flex size-10 shrink-0 overflow-hidden rounded-full",
          className,
        )}
        {...props}
      >
        {src ? (
          <AvatarPrimitive.Image
            data-slot="avatar-image"
            src={src}
            alt={alt ?? name}
            className={cn("aspect-square size-full object-cover", !showImage && "hidden")}
            onLoad={() => setLoaded(true)}
            onError={() => setFailed(true)}
          />
        ) : null}
        <AvatarPrimitive.Fallback
          data-slot="avatar-fallback"
          className={cn(
            "bg-muted text-muted-foreground flex size-full items-center justify-center rounded-full text-sm font-medium",
            showImage && "hidden",
          )}
        >
          {fallbackContent}
        </AvatarPrimitive.Fallback>
      </AvatarPrimitive.Root>
    );
  },
);
Avatar.displayName = "Avatar";

Related examples

Sizes & fallbackImage, initials, and compact count badge.

Profile rowAvatar beside name and email.

Browse the full examples gallery