Avatar

Avatar component with different shapes, sizes, borders, statuses, fallbacks, and groups.

← Back to components

Basic

<Avatar src="/images/avatar-1.png" alt="John Doe" size="xs" />
<Avatar src="/images/avatar-1.png" alt="John Doe" size="sm" />
<Avatar src="/images/avatar-2.png" alt="Jane Smith" size="md" />
<Avatar src="/images/avatar-3.png" alt="Mike Johnson" size="lg" />
<Avatar src="/images/avatar-1.png" alt="John Doe" size="xl" />
<Avatar src="/images/avatar-2.png" alt="Jane Smith" size="2xl" />

With initials

<Avatar initials="JD" size="sm" />
<Avatar initials="AS" size="md" />
<Avatar initials="MJ" size="lg" />

With border

<Avatar src="/images/avatar-1.png" alt="John Doe" size="sm" border />
<Avatar src="/images/avatar-2.png" alt="Jane Smith" size="md" border />
<Avatar initials="MJ" size="lg" border />

Non rounded

<Avatar src="/images/avatar-1.png" alt="John Doe" size="sm" rounded={false} />
<Avatar src="/images/avatar-2.png" alt="Jane Smith" size="md" rounded={false} />
<Avatar initials="MJ" size="lg" rounded={false} />

Status

<Avatar src="/images/avatar-1.png" alt="John Doe" size="sm" status="online" />
<Avatar src="/images/avatar-2.png" alt="Jane Smith" size="md" status="online" />
<Avatar initials="MJ" size="lg" status="offline" />

Verified

<Avatar src="/images/avatar-3.png" verified size="md" />
<Avatar initials="VU" verified size="lg" />

With count

<Avatar initials="JD" size="sm" count={3} />
<Avatar src="/images/avatar-1.png" alt="John Doe" size="md" count={12} />
<Avatar initials="AS" size="lg" count={99} />

With custom badge

<Avatar
  src="/images/avatar-4.png"
  size="md"
  badge={
    <div className="absolute -right-1 -bottom-1 size-4 rounded-full bg-utility-blue-500 flex items-center justify-center">
      <span className="text-white text-xs">+</span>
    </div>
  }
/>

Focusable

Use focusable when the avatar is nested inside an interactive element (e.g. a link or button) that carries the group class. The focus ring is triggered by group-focus-visible.

{/* The parent must have className="group" for the focus ring to work */}
<a href="/profile" className="group rounded-full">
  <Avatar src="/images/avatar-1.png" alt="John Doe" size="md" focusable />
</a>

Profile photo

A dedicated component for large profile photos. Includes a highlight border effect and supports status and verified badges.

<AvatarProfilePhoto src="/images/avatar-1.png" alt="John Doe" size="sm" />
<AvatarProfilePhoto src="/images/avatar-2.png" alt="Jane Smith" size="md" />
<AvatarProfilePhoto src="/images/avatar-3.png" alt="Mike Johnson" size="lg" />

{/* With badges */}
<AvatarProfilePhoto initials="JD" size="sm" verified />
<AvatarProfilePhoto initials="JS" size="md" status="online" />
<AvatarProfilePhoto size="lg" status="offline" />

AvatarLabel

<AvatarLabel
    size="sm"
    src="/images/avatar-4.png"
    alt="Rhye"
    title="Rhye"
    subtitle="rhye@untitledui.com"
/>
<AvatarLabel
    size="md"
    src="/images/avatar-4.png"
    alt="Rhye"
    title="Rhye"
    subtitle="rhye@untitledui.com"
/>
<AvatarLabel
    size="lg"
    src="/images/avatar-4.png"
    alt="Rhye"
    title="Rhye"
    subtitle="rhye@untitledui.com"
/>

AvatarGroup

<div className="flex gap-2 items-center">
    <AvatarGroup
        size="md"
        max={4}
        items={[
            { src: "/images/avatar-1.png", alt: "User 1" },
            { src: "/images/avatar-2.png", alt: "User 2" },
            { src: "/images/avatar-3.png", alt: "User 3" },
            { src: "/images/avatar-4.png", alt: "User 4" },
            { initials: "AB" },
            { initials: "CD" },
        ]}
    />
    <AvatarAddButton size="md" onClick={() => console.log("add")} />
</div>

API Reference

Avatar

Prop	Type	Default	Description
src?	string \| null	—	Image source URL.
alt?	string	—	Alternative text for the image. Pass an empty string ("") for decorative avatars.
initials?	string	—	Fallback initials shown when no image is available.
placeholderIcon?	FC<{ className?: string }>	—	Icon component shown when no image or initials are provided.
placeholder?	ReactNode	—	Arbitrary fallback node shown when no image, initials, or icon are provided.
size?	"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"	"md"	Avatar dimensions.
rounded?	boolean	true	Toggles full rounding (pill). Set to false for a rounded-md square shape.
border?	boolean	false	Displays an outer ring border.
status?	"online" \| "offline"	—	Displays a presence indicator badge.
verified?	boolean	false	Displays a verified tick badge.
count?	number	—	Displays a numeric count badge (e.g. for notifications).
badge?	ReactNode	—	Custom badge node. Ignored when status, verified, or count are set.
focusable?	boolean	false	Shows a focus ring when a parent element with className="group" receives focus-visible. Use when nesting Avatar inside a link or button.
contentClassName?	string	—	Class name applied to the inner content wrapper.
className?	string	—	Class name applied to the root element.

AvatarProfilePhoto

Dedicated component for large profile photos. Accepts the same props as Avatar with size restricted to "sm" | "md" | "lg".

Prop	Type	Default	Description
size	"sm" \| "md" \| "lg"	"md"	Profile photo size.
src?	string	—	Image source URL.
alt?	string	—	Alternative text for the image.
initials?	string	—	Fallback initials.
status?	"online" \| "offline"	—	Presence indicator badge.
verified?	boolean	false	Verified tick badge.
badge?	ReactNode	—	Custom badge node.
className?	string	—	Additional class names.

AvatarLabel

Combines an avatar with a title and subtitle. Accepts all Avatar props with size restricted to "sm" | "md" | "lg".

Prop	Type	Default	Description
title	string \| ReactNode	—	Primary label.
subtitle	string \| ReactNode	—	Secondary label (truncated on overflow).
size	"sm" \| "md" \| "lg"	—	Controls text sizing and avatar size.
avatarClassName?	string	—	Class name applied to the Avatar element.
className?	string	—	Class name applied to the root figure element.

AvatarGroup

Prop	Type	Default	Description
items	Omit<AvatarProps, "size">[]	[]	List of avatar items to render.
size?	AvatarProps["size"]	"md"	Uniform size applied to all avatars in the group.
max?	number	3	Maximum number of avatars shown before a count badge.
avatarClassName?	string	—	Additional class names applied to each Avatar.
className?	string	—	Additional class names applied to the group container.

AvatarAddButton

A dashed-border button used alongside AvatarGroup to add new members.

Prop	Type	Default	Description
size	"xs" \| "sm" \| "md"	—	Button size. Should match the AvatarGroup size.
title?	string	"Add user"	Tooltip text and aria-label.
className?	string	—	Additional class names.