Skip to content
shadcn.io
shadcn.io is not affiliated with official shadcn/ui

Shadcn Avatar for React and Tailwind

Displays a user's profile image with fallback.

VV
CN
VV
SA
PV
+2

Installation

bunx --bun shadcn@latest add https://kit.dev/r/avatar.json

Anatomy

Avatar
├── AvatarImage
└── AvatarFallback

AvatarGroup
├── AvatarGroupCount
└── Avatar
    ├── AvatarImage
    ├── AvatarFallback
    └── AvatarBadge

Usage

import { 
  Avatar, 
  AvatarImage, 
  AvatarFallback 
} from "@/components/ui/avatar";
<Avatar>
  <AvatarImage src="https://github.com/vinihvc.png" />
  <AvatarFallback>VV</AvatarFallback>
</Avatar>

Events

Use onStatusChange to listen for image load and error.

Root Provider

Use useAvatar with AvatarRootProvider when you need the API outside the tree.

Sizes

Small

Medium

Large

Examples

Avatar Group

Badge

Badge with Icon

Fallback with icon

Context

Use AvatarContext or useAvatarContext to read whether the image has loaded.

Avatar Group Count

Avatar Group Count Icon

Avatar with Popover

Avatar with Hover Card

Custom Size

Use size-* to set the size of the avatar.

You can use breakpoint utilities to change the size at different screen sizes.

  md:size-4 lg:size-8

Custom Radius

Use rounded-* to set the radius of the avatar.

You can use breakpoint utilities to change the radius at different screen sizes.

md:rounded-full lg:rounded-lg

Guides

Next.js Image

AvatarImage is a native img. To use next/image, merge Ark image props with getImageProps and prefer visibility over hidden:

import { getImageProps, type ImageProps } from "next/image";
import { Avatar, AvatarFallback, useAvatarContext } from "@/components/ui/avatar";

const AvatarNextImage = (props: ImageProps) => {
  const avatar = useAvatarContext();
  const { hidden, ...arkImageProps } = avatar.getImageProps();
  const nextImage = getImageProps(props);

  return (
    <img
      {...arkImageProps}
      {...nextImage.props}
      alt={props.alt}
      style={{
        ...props.style,
        visibility: hidden ? "hidden" : "visible",
      }}
    />
  );
};

<Avatar>
  <AvatarFallback>JD</AvatarFallback>
  <AvatarNextImage alt="" height={80} src="..." width={80} />
</Avatar>

API Reference

asChild merges props onto a single child element.

Avatar

Root. Renders a div.

PropTypeDefaultDescription
size"sm" | "md" | "lg""md"sm is size-6, md is size-8, lg is size-10. Override with size-*.
asChildbooleanfalseRender the child element instead of a div.
classNamestring-Class names on the root.
dir"ltr" | "rtl"-Text direction. Usually inherited from LocaleProvider.
idstring-Unique id for the machine.
idsPartial<{ root: string; image: string; fallback: string }>-Element ids for composition.
onStatusChange(details: StatusChangeDetails) => void-Called when loading status changes. StatusChangeDetails is { status: "loaded" | "error" }.
AttributeDescription
data-slotavatar
data-size"sm", "md", or "lg"
data-scopeavatar
data-partroot

AvatarImage

Profile image. Hidden until loaded. Renders an img.

PropTypeDefaultDescription
srcstring-Image URL.
altstring-Accessible name. Required when the avatar represents a person.
asChildbooleanfalseMerge onto a single child.
classNamestring-Class names on the image.
AttributeDescription
data-slotavatar-image
data-scopeavatar
data-partimage
data-state"visible" when loaded, "hidden" otherwise

AvatarFallback

Shown while the image is loading or after error. Renders a span. Initials or a decorative icon.

PropTypeDefaultDescription
asChildbooleanfalseMerge onto a single child.
classNamestring-Class names on the fallback.
AttributeDescription
data-slotavatar-fallback
data-scopeavatar
data-partfallback
data-state"visible" when the image is not loaded, "hidden" when it is

AvatarBadge

Status indicator on the end-bottom corner. Renders Status. Hidden icons at size="sm".

PropTypeDefaultDescription
variant"default" | "success" | "info" | "warning" | "destructive""default"Status color.
asChildbooleanfalseMerge onto a single child.
classNamestring-Class names on the badge.
AttributeDescription
data-slotavatar-badge

AvatarGroup

Overlapping row of avatars. Renders a div.

PropTypeDefaultDescription
asChildbooleanfalseMerge onto a single child.
classNamestring-Class names on the group.
AttributeDescription
data-slotavatar-group

AvatarGroupCount

Overflow count (+2). Renders a div. Size it with size-* to match the avatars.

PropTypeDefaultDescription
asChildbooleanfalseMerge onto a single child.
classNamestring-Class names on the count.
AttributeDescription
data-slotavatar-group-count

AvatarRootProvider

Root alternative that takes the API from useAvatar.

PropTypeDefaultDescription
valueUseAvatarReturnrequiredReturn value of useAvatar().
size"sm" | "md" | "lg""md"Same size tokens as Avatar.
asChildbooleanfalseRender the child element instead of a div.
classNamestring-Class names on the root.

useAvatar

Creates the avatar API for AvatarRootProvider.

const avatar = useAvatar();
avatar.setSrc("https://example.com/photo.png");

AvatarContext / useAvatarContext

Render-prop or hook access to load state. Use inside Avatar or AvatarRootProvider.

PropertyTypeDescription
loadedbooleanWhether the image has loaded.
setSrc(src: string) => voidSet the image src.
setLoaded() => voidMark the image as loaded.
setError() => voidMark the image as failed.

AvatarContext children: (context) => ReactNode.

Accessibility

The image alt should name the person or entity. If there is no image and the fallback is only an icon, set aria-label on Avatar. Decorative icons in the fallback or badge should be aria-hidden="true".

Keyboard support

The avatar is not interactive. If you wrap it in a link or button (asChild or a parent control), that control’s keys apply (Enter, Tab).