Avatar

A person’s picture, or their initials when there isn’t one.

PNPNPNJZJL

Sam Kim

Online

PNJLSK

Fig. 1 Avatars with photos, initials, and an overlapping group.

When to use it

Use Avatar wherever a person appears: comments, assignees, members. The initials fallback keeps the layout steady while images load or when there’s no photo.

Stack several with AvatarGroup, and summarize the rest with a count.

How it behaves

AvatarImage shows once the image loads; AvatarFallback shows while it loads or if it fails. Give the image alt text and keep initials short.

size is sm (24px), default (32px), or lg (40px). AvatarBadge adds a status dot; give it a name and use a status color such as bg-success.

AvatarGroup overlaps avatars with a ring in the page background; AvatarGroupCount summarizes the rest. Label the group and the count for screen readers.

Initials sit on an opaque muted fill so stacked avatars never show through each other. A faint outline appears only behind a loaded image.

Build it

Add it with the shadcn CLI:

Terminal

A complete example. Change the values to fit your product:

avatar-example.tsx

The full source is yours to edit once installed:

avatar.tsx

1import { cn, mergeClassName } from "@/registry/lib/utils"2import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"3import type * as React from "react"4 5// The faint outline appears only once an image has loaded, to separate light photos from the page; initials6// sit on an opaque muted fill so stacked avatars never show through each other.7function Avatar({8  className,9  size = "default",10  ...props11}: AvatarPrimitive.Root.Props & {12  size?: "default" | "sm" | "lg"13}) {14  return (15    <AvatarPrimitive.Root16      data-slot="avatar"17      data-size={size}18      className={mergeClassName(19        "group/avatar relative flex size-8 shrink-0 rounded-full select-none after:pointer-events-none after:absolute after:inset-0 after:rounded-full has-[img]:after:border has-[img]:after:border-foreground/10 data-[size=lg]:size-10 data-[size=sm]:size-6",20        className21      )}22      {...props}23    />24  )25}26 27function AvatarImage({ className, ...props }: AvatarPrimitive.Image.Props) {28  return (29    <AvatarPrimitive.Image30      data-slot="avatar-image"31      className={mergeClassName("aspect-square size-full rounded-full object-cover", className)}32      {...props}33    />34  )35}36 37// Initials use the label role, larger on the large size.38function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props) {39  return (40    <AvatarPrimitive.Fallback41      data-slot="avatar-fallback"42      className={mergeClassName(43        "flex size-full items-center justify-center rounded-full bg-muted label-sm text-muted-foreground group-data-[size=lg]/avatar:label-md",44        className45      )}46      {...props}47    />48  )49}50 51function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {52  return (53    <span54      data-slot="avatar-badge"55      className={cn(56        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground bg-blend-color ring-2 ring-background select-none",57        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",58        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",59        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",60        className61      )}62      {...props}63    />64  )65}66 67function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {68  return (69    <div70      data-slot="avatar-group"71      className={cn(72        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",73        className74      )}75      {...props}76    />77  )78}79 80function AvatarGroupCount({ className, ...props }: React.ComponentProps<"div">) {81  return (82    <div83      data-slot="avatar-group-count"84      className={cn(85        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted label-sm text-muted-foreground ring-2 ring-background 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",86        className87      )}88      {...props}89    />90  )91}92 93export { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage }94