avatar
An image element with a fallback for representing the user.
Philosophy
Identity in UI starts with a face. Avatars humanize interfaces by giving users a visual anchor. We support both single avatars and groups because social context — seeing who else is involved — is a fundamental interaction pattern. The fallback-to-initials behavior ensures graceful degradation when images fail.
Installation
npx @gentleduck/cli add avatar
npx @gentleduck/cli add avatar
Usage
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"<Avatar>
<AvatarImage src="https://github.com/wildduck2.png" alt="wildduck" />
<AvatarFallback>WD</AvatarFallback>
</Avatar><Avatar>
<AvatarImage src="https://github.com/wildduck2.png" alt="wildduck" />
<AvatarFallback>WD</AvatarFallback>
</Avatar>API Reference
Avatar
The root container rendered as a span. Provides context for AvatarImage and AvatarFallback.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional class names for styling the avatar container |
...props | React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root> | -- | Additional props inherited from the avatar primitive root (span element) |
AvatarImage
The img element inside the avatar. Automatically tracks loading status and hides when the image fails.
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | -- | Image source URL |
alt | string | -- | Alternate text for the image |
onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | -- | Callback when the image loading status changes |
className | string | -- | Additional class names for styling the image |
...props | React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image> | -- | Additional props inherited from the avatar image primitive |
AvatarFallback
Content displayed when the image has not loaded. Typically initials or an icon.
| Prop | Type | Default | Description |
|---|---|---|---|
delayMs | number | -- | Optional delay in milliseconds before showing the fallback (avoids flicker for fast-loading images) |
className | string | -- | Additional class names for styling the fallback |
children | React.ReactNode | -- | Fallback content (e.g. initials) |
...props | React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback> | -- | Additional props inherited from the avatar fallback primitive |
AvatarGroup
| Prop | Type | Default | Description |
|---|---|---|---|
imgs | { src?: string; alt?: string; fallback?: string; id?: string }[] | (required) | Array of avatar data objects. Fallback text is truncated to 2 characters. |
maxVisible | number | 3 | Maximum number of avatars to display before showing a +N overflow counter |
className | string | -- | Additional class names for styling the avatar group container |
...props | React.HTMLAttributes<HTMLDivElement> | -- | Additional props to spread to the container div |