Avatar

An avatar is a visual representation of a user or entity.

<Avatar>
  <AvatarImage alt="@mehdibha" />
  <AvatarFallback>MB</AvatarFallback>
</Avatar>

Installation

npm

pnpm

yarn

bun

npx shadcn@latest add @dotui/avatar

Usage

Use avatars to represent users or entities with an image or initials.

import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar'

<Avatar>
  <AvatarImage src="https://github.com/mehdibha.png" alt="@mehdibha" />
  <AvatarFallback>MB</AvatarFallback>
</Avatar>

Anatomy

import {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarBadge,
  AvatarGroup,
  AvatarGroupCount,
} from '@/components/ui/avatar'

<Avatar>
  <AvatarImage />
  <AvatarFallback />
  <AvatarBadge />
</Avatar>

<AvatarGroup>
  <Avatar>{/* ... */}</Avatar>
  <AvatarGroupCount />
</AvatarGroup>

Avatar is the container. AvatarImage renders the picture, AvatarFallback the initials or icon shown in its place, and AvatarBadge a status indicator overlaid on the corner. AvatarGroup stacks avatars with an overlapping layout, and AvatarGroupCount shows the remaining count.

Fallback

AvatarImage and AvatarFallback share loading state, so you always render both. AvatarImage appears only once its src finishes loading; until then — and if loading fails — AvatarFallback is shown instead.

Examples

Basic

Badge with notification

Group

MTD

Group with count

MTD+3

API Reference

Avatar

A visual representation of a user or entity, displayed as an image, initials, or placeholder.

Supports all span attributes.

Prop	Type	Default
	`"lg" \| "md" \| "sm"`	`'md'`

AvatarImage

The image element displayed within the avatar. Automatically hidden when the image fails to load.

Supports all img attributes.

Prop	Type	Default
	`string`	`—`

AvatarFallback

Content displayed when the avatar image fails to load. Typically shows initials or an icon.

Supports all span attributes.

Prop	Type	Default

AvatarBadge

A small indicator displayed on the avatar, typically used to show online status.

Supports all span attributes.

Prop	Type	Default

AvatarGroup

A group container that displays multiple avatars together with overlapping layout.

Supports all div attributes.

Prop	Type	Default
	`"lg" \| "md" \| "sm"`	`'md'`

AvatarGroupCount

A count indicator displayed at the end of an avatar group to show remaining items.

Supports all span attributes.

Prop	Type	Default

Last updated on 7/7/2026