Avatar
A person or workspace image with an initials fallback, four sizes, a presence dot and overlapping groups.
npx prodular-ui add avatarSizes
xs 20px, sm 24px, default 32px, lg 40px. The fallback shows while the image loads or if it fails.
MMOMOMO
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
export default function AvatarSizes() { return ( <div className="flex items-center gap-4"> <Avatar size="xs"> <AvatarFallback>M</AvatarFallback> </Avatar> <Avatar size="sm"> <AvatarFallback>MO</AvatarFallback> </Avatar> <Avatar> <AvatarFallback>MO</AvatarFallback> </Avatar> <Avatar size="lg"> <AvatarFallback>MO</AvatarFallback> </Avatar> </div> )}Group
Overlapping avatars with a count for the rest. The group sets the size for every child.
import { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount,} from "@/components/ui/avatar"
const people = [ { name: "Maya Okafor", initials: "MO" }, { name: "Daniel Reyes", initials: "DR" }, { name: "Priya Raman", initials: "PR" }, { name: "Tomas Lindqvist", initials: "TL" },]
export default function AvatarGroupDemo() { return ( <div className="flex flex-col items-center gap-6"> {(["sm", "default", "lg"] as const).map((size) => ( <AvatarGroup key={size} size={size}> {people.map((p) => ( <Avatar key={p.name}> <AvatarFallback title={p.name}>{p.initials}</AvatarFallback> </Avatar> ))} <AvatarGroupCount aria-label="3 more members">+3</AvatarGroupCount> </AvatarGroup> ))} </div> )}Presence
AvatarStatus shows online, away, busy or offline and announces it to screen readers.
- MOMaya OkaforSupport leadonline
- DRDaniel ReyesAccount executiveaway
- HSHana SatoSolutions engineerbusy
- OGOwen GallagherBillingoffline
import { Avatar, AvatarFallback, AvatarStatus } from "@/components/ui/avatar"
const people = [ { name: "Maya Okafor", role: "Support lead", initials: "MO", status: "online" }, { name: "Daniel Reyes", role: "Account executive", initials: "DR", status: "away" }, { name: "Hana Sato", role: "Solutions engineer", initials: "HS", status: "busy" }, { name: "Owen Gallagher", role: "Billing", initials: "OG", status: "offline" },] as const
export default function AvatarStatusDemo() { return ( <ul className="flex w-full max-w-xs flex-col divide-y"> {people.map((p) => ( <li key={p.name} className="flex items-center gap-3 py-2.5 first:pt-0 last:pb-0"> <Avatar> <AvatarFallback>{p.initials}</AvatarFallback> <AvatarStatus status={p.status} /> </Avatar> <div className="flex min-w-0 flex-col"> <span className="text-sm font-medium">{p.name}</span> <span className="text-[13px] text-muted-foreground">{p.role}</span> </div> <span className="ml-auto text-[13px] text-muted-foreground capitalize">{p.status}</span> </li> ))} </ul> )}Anatomy
<Avatar> <AvatarImage src="/maya.jpg" alt="Maya Okafor" /> <AvatarFallback>MO</AvatarFallback> <AvatarStatus status="online" /></Avatar>Guidance
Use it when
- Show who owns, created or is assigned to something.
- Use AvatarGroup to show who has access or who is viewing, capped at four or five faces.
- Use AvatarStatus where presence changes what people do next, such as assigning a ticket.
Avoid
- Avatars as the only label for a person. Show the name next to it, or in a tooltip.
- Presence dots on lists where presence is not live.
- Groups of more than five avatars. Show four and a count.
Rules for AI agents
Published in llms-full.txt, the registry and the MCP server, so coding agents follow them when they build with this component.
- Always include AvatarFallback with one or two initials. Use one initial at size xs.
- Give AvatarImage an alt with the person's full name.
- Set size on AvatarGroup, not on each Avatar inside it.
- End a group with AvatarGroupCount, labeled with aria-label, for example aria-label="3 more members".
- Map presence with AvatarStatus status: online, away, busy, offline. Do not draw your own dot.
- On a surface that is not a card, set [--avatar-ring:var(--color-background)] on a parent so the rings match the background.
API
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "xs" | "sm" | "default" | "lg" | "default" | 20, 24, 32 or 40px. Inherits from AvatarGroup. |
AvatarGroup
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "xs" | "sm" | "default" | "lg" | Size for every avatar and the count in the group. |
AvatarStatus
| Prop | Type | Default | Description |
|---|---|---|---|
| status | "online" | "away" | "busy" | "offline" | Presence. Colored with success, warning, destructive or gray. | |
| label | string | Accessible label. Defaults to the status name. |
AvatarBadge
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | A small primary badge at the bottom right, optionally with an icon. |
Installation
The Prodular UI CLI adds the source to components/ui with everything it depends on. In a project that already uses shadcn/ui, the shadcn CLI installs it from the Prodular registry too. See Installation for the first setup.
npx prodular-ui add avatar# or, with the registry in components.jsonnpx shadcn@latest add @prodular/avatar