Shadcn Avatar
React avatar for profile photos, comments, and team lists. Built with TypeScript and Tailwind CSS for Next.js using Base UI — image, fallback, badge, and groups.
An avatar is a face: the photo first, initials if the image fails. Use it on a comment, a chat row, a nav account trigger, or a stacked team. AvatarBadge is the status dot; AvatarGroup overlaps faces and can show a leftover count.
Looking for a neobrutalism version for shadcn?
Same avatar, thicker borders. The NeoBrutalism avatar is the kit if you want that look.
Usage
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"<Avatar>
<AvatarImage src="https://avatars.githubusercontent.com/u/223274014?s=200&v=4" alt="@shadcnio" />
<AvatarFallback>SI</AvatarFallback>
</Avatar>size is sm, default, or lg. AvatarFallback is what shows while the image loads or after it fails.
Composition
Basic
Photo and initials. If the image fails, you still get a circle.
Badge
AvatarBadge sits on the bottom-right. Color it for presence.
Badge with Icon
Drop an icon in AvatarBadge — a plus, a check, whatever the action is.
Avatar Group
AvatarGroup overlaps faces with a ring. Three is enough for a team row.
Avatar Group Count
AvatarGroupCount is the leftover chip — +3, not the next face.
Avatar Group with Icon
Same slot, an icon instead of a number — usually add.
Sizes
size is sm, default, or lg. Badge and group count follow the same data-size.
Dropdown
Sit the avatar in a ghost icon Button and open a Dropdown Menu.
RTL
Wrap with DirectionProvider and dir="rtl". The group still overlaps; the count is Arabic.
API
Prop
Type
AvatarImage
Prop
Type
AvatarFallback
Prop
Type
AvatarBadge is a span — color it with className. AvatarGroup overlaps children. AvatarGroupCount is the leftover chip.
Notes
Fallback is the face when the photo dies
Always set alt on AvatarImage. A missing src or a 404 is an empty circle unless AvatarFallback has initials or an icon. delayMs={600} hides the initials flash while a good image loads.
AvatarGroup already rings and overlaps — do not wrap it in another negative-margin stack.
With other components
Account menu trigger
ButtonGhost icon trigger
TooltipName on hover
Hover CardProfile on hover
ItemFace in a list row
MessageSender in a thread
Questions
Related
Was this page helpful?
Sign in to leave feedback.
Attachment
React attachment for files in a composer or thread. Built with TypeScript and Tailwind CSS for Next.js using Base UI — upload states, sizes, and a full-card trigger.
Badge
React badge for status, counts, and labels. Built with TypeScript and Tailwind CSS for Next.js using Base UI — six variants, icons, and render links on a span.