ui/components/avatar

Avatar

Terminal-inspired avatar with image support, monospace initials fallback, and group stacking with overflow.

Preview

tsx

1 import { Avatar } from "@/components/ui/avatar";2 3 export default function AvatarDefault() {4   return (5     <div className="flex items-center gap-4">6       <Avatar7         src="data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2064%2064'%3E%3Crect%20width='64'%20height='64'%20fill='%23111827'/%3E%3Cpath%20fill='%2322d3ee'%20d='M12%2012h16v16H12zM36%2012h16v16H36zM20%2036h24v12H20z'/%3E%3Cpath%20fill='%23f8fafc'%20d='M28%2028h8v8h-8zM12%2052h40v4H12z'/%3E%3C/svg%3E"8         alt="Felix"9         fallback="FX"10       />11       <Avatar fallback="JD" />12       <Avatar fallback="AB" size="lg" />13     </div>14   );15 }16

Installation

$pnpm exec dgadd add ui/avatar

[Installs to]src/components/ui/avatar[Item]ui/avatar

dgadd ships in @diffgazer/add on npm: pnpm add -D @diffgazer/add puts it on pnpm exec, and npx @diffgazer/add runs it without the install.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS from the installed package.

Usage

tsx

1 import { Avatar } from "@/components/ui/avatar";2 3 export default function AvatarDefault() {4   return (5     <div className="flex items-center gap-4">6       <Avatar7         src="data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2064%2064'%3E%3Crect%20width='64'%20height='64'%20fill='%23111827'/%3E%3Cpath%20fill='%2322d3ee'%20d='M12%2012h16v16H12zM36%2012h16v16H36zM20%2036h24v12H20z'/%3E%3Cpath%20fill='%23f8fafc'%20d='M28%2028h8v8h-8zM12%2052h40v4H12z'/%3E%3C/svg%3E"8         alt="Felix"9         fallback="FX"10       />11       <Avatar fallback="JD" />12       <Avatar fallback="AB" size="lg" />13     </div>14   );15 }16

Examples

Sizes

Preview

tsx

1 import { Avatar } from "@/components/ui/avatar";2 3 export default function AvatarSizes() {4   return (5     <div className="flex items-center gap-4">6       <Avatar fallback="SM" size="sm" />7       <Avatar fallback="MD" size="md" />8       <Avatar fallback="LG" size="lg" />9     </div>10   );11 }12

Group with Overflow

Preview

tsx

1 import { Avatar, AvatarGroup } from "@/components/ui/avatar";2 3 const users = [4   { initials: "JD" },5   { initials: "AB" },6   { initials: "CD" },7   { initials: "EF" },8   { initials: "GH" },9   { initials: "KL" },10   { initials: "MN" },11 ];12 13 // AvatarGroup defaults its accessible name to "Avatars", so three groups on one14 // page would all announce the same. Each caption doubles as its group's name.15 const OVERLAP_CAPTION = "overlap (default) — max=3";16 const GAP_CAPTION = 'spacing="gap" — max=3';17 const RESPONSIVE_CAPTION = "responsive (no max) — resize to see";18 19 export default function AvatarGroupExample() {20   return (21     <div className="flex flex-col gap-4">22       <div className="flex flex-col gap-2">23         <span className="text-xs font-mono text-muted-foreground">{OVERLAP_CAPTION}</span>24         <AvatarGroup max={3} size="md" aria-label={OVERLAP_CAPTION}>25           {users.map((u) => (26             <Avatar key={u.initials} fallback={u.initials} />27           ))}28         </AvatarGroup>29       </div>30 31       <div className="flex flex-col gap-2">32         <span className="text-xs font-mono text-muted-foreground">{GAP_CAPTION}</span>33         <AvatarGroup max={3} size="md" spacing="gap" aria-label={GAP_CAPTION}>34           {users.map((u) => (35             <Avatar key={u.initials} fallback={u.initials} />36           ))}37         </AvatarGroup>38       </div>39 40       <div className="flex flex-col gap-2">41         <span className="text-xs font-mono text-muted-foreground">{RESPONSIVE_CAPTION}</span>42         <div className="w-20 resize-x overflow-auto border border-dashed border-foreground/20 p-2">43           <AvatarGroup size="md" aria-label={RESPONSIVE_CAPTION}>44             {users.map((u) => (45               <Avatar key={u.initials} fallback={u.initials} />46             ))}47           </AvatarGroup>48         </div>49       </div>50     </div>51   );52 }53

API Reference

Avatar

Name	Type	Default	Description
src	string	—	Image URL. Ignored when children are provided.
alt	string	—	Image alt text and accessible name. When omitted, falls back to a string `fallback`. When neither is set, the avatar uses role="presentation".
fallback	ReactNode	"?"	Shown when the image is loading, missing, or fails.
size	"sm" \| "md" \| "lg"	"md"	Square size token. Inherits from an AvatarGroup parent when unset.
onStatusChange	(status: "loading" \| "loaded" \| "error") => void	—	Fired when the image load status changes. Fires for the active image only.
children	ReactNode	—	Custom inner content. Replaces the default AvatarImage + AvatarFallback composition.

AvatarImage

Name	Type	Default	Description
src	string	—	Image URL.
alt	string	""	Accessible name for the image. Defaults to `""`, treating the avatar as decorative so it is skipped by assistive tech and the surrounding control supplies the accessible name. Pass an explicit `alt` when the avatar is the sole label for its container.

AvatarFallback

Name	Type	Default	Description
src	string	—	Cascading fallback image. Tried before rendering children.
children	ReactNode	—	Initials or icon shown when no fallback image is available.

AvatarGroup

Name	Type	Default	Description
max	number	—	Hard cap on visible avatars. Values are rounded down; negative and non-finite values become zero. When omitted, AvatarGroup measures overflow with Overflow.
spacing	"overlap" \| "gap"	"overlap"	Overlap stacks avatars; gap spaces them apart.
size	"sm" \| "md" \| "lg" \| null	"md"	Default size applied to descendant Avatars that do not set their own size.
aria-label	string	"Avatars"	Accessible label for the group container (rendered with role="group").
childrenrequired	ReactNode	—	Avatar elements.

AvatarIndicator

Name	Type	Default	Description
countrequired	number	—	Number rendered as "+N". Used by AvatarGroup for overflow but available standalone.
size	"sm" \| "md" \| "lg"	—	Size override. Falls back to the AvatarGroup size.
getLabel	(count: number) => string	—	Localizes the indicator accessible name. Defaults to the "N more" pattern when neither getLabel nor aria-label is provided.

Accessibility

Notes

Image Fallback

When src fails to load, Avatar falls back to the fallback initials. If no fallback is provided, '?' is shown.

Terminal Style

Square shape with a border and monospace font for initials — following the @diffgazer/ui terminal-inspired aesthetic.

Spacing

AvatarGroup supports spacing='overlap' (default, stacked look) or spacing='gap' (spaced apart). Use 'gap' inside Select triggers or inline layouts where overlap looks cramped.

Composition

Avatar works standalone or inside AvatarGroup. Combine Avatar with public Select parts to build avatar pickers.

Source

Install via CLI: pnpm exec dgadd add ui/avatar. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Avatar

Installation

Usage

Examples

Sizes

Group with Overflow

API Reference

Avatar

AvatarImage

AvatarFallback

AvatarGroup

AvatarIndicator

Accessibility

Notes

Image Fallback

Terminal Style

Spacing

Composition

Source

View component source (48 files)