Components
Avatar
An image element with a fallback for representing the user. Use it for people and accounts: the fallback shows initials while the image loads or if it is missing.
Preview
DHCN
DH
Rendered with live Cognition tokens: the fallback surface and the status ring remap on theme change, no dark: classes.
Sizes
CNCNCN
<Avatar className="size-6">…</Avatar> {/* sm */}
<Avatar className="size-8">…</Avatar> {/* default */}
<Avatar className="size-10">…</Avatar> {/* lg */}Sizing is a className on the root. size-6 (sm), size-8 (default), size-10 (lg).
States
DH
<Avatar>
<AvatarImage src={user.avatarUrl} alt={user.name} />
<AvatarFallback>CN</AvatarFallback>
</Avatar>CN
<Avatar>
<AvatarFallback>CN</AvatarFallback>
</Avatar>DH
<div className="relative inline-flex">
<Avatar>…</Avatar>
<span className="absolute bottom-0 right-0 size-2.5 rounded-full
border-2 border-background-default bg-feedback-success" />
</div>CNABJL+3
<div className="flex -space-x-2">
<Avatar className="size-8 border-2 border-background-default">…</Avatar>
<Avatar className="size-8 border-2 border-background-default">…</Avatar>
<Avatar className="size-8 border-2 border-background-default">
<AvatarFallback>+3</AvatarFallback>
</Avatar>
</div>The image falls back to AvatarFallback on load or error. The status dot and the overlapping group are compositions: a positioned span and flex -space-x-2 with a border ring.
API
Part
Props
Description
Avatar
className
Root. Clips children to a circle; set the size with size-6 / size-8 / size-10.
AvatarImage
src, alt
The image. Hidden until it loads or errors: the fallback shows instead.
AvatarFallback
delayMs
Shown while the image loads or if it is missing. Use initials or an icon.
Don't and Do
Don't
Don't use an Avatar as a generic image or icon container, and don't ship one without an AvatarFallback: the initials or icon are what render while the image loads or if it 404s.
Do
<Avatar>
<AvatarImage src={src} alt={name} />
<AvatarFallback>{initials}</AvatarFallback>
</Avatar>import { Avatar, AvatarImage, AvatarFallback } from "@/components/ui/avatar";
export function UserAvatar({ user }) {
return (
<Avatar>
<AvatarImage src={user.avatarUrl} alt={user.name} />
<AvatarFallback>{initials(user.name)}</AvatarFallback>
</Avatar>
);
}