Avatar
An image element with a fallback for representing the user.
Installation
$npx maddex add Avatar
Basic
Start with AvatarImage and AvatarFallback. The image fades in when it loads, while the fallback stays ready for empty or broken sources.
Preview
CN
@shadcn
Design systems
1<div class="flex items-center gap-4 rounded-xl border bg-background px-5 py-4 shadow-sm">
2 <x-avatar class="size-12">
3 <x-avatar-image src="https://github.com/shadcn.png" alt="@shadcn" />
4 <x-avatar-fallback>CN</x-avatar-fallback>
5 </x-avatar>
6
7 <div class="space-y-1 text-left">
8 <p class="text-sm font-semibold leading-none">@shadcn</p>
9 <p class="text-sm text-muted-foreground">Design systems</p>
10 </div>
11</div>
Semantic Fallbacks
Style the fallback with semantic tokens so broken avatars still communicate a meaningful state.
Preview
JD
ER
QA
1<div class="flex flex-wrap items-center justify-center gap-4">
2 <x-avatar class="size-12 ring-1 ring-border">
3 <x-avatar-image src="https://github.com/this-user-does-not-exist.png" alt="@jamie" />
4 <x-avatar-fallback class="bg-primary text-primary-foreground">JD</x-avatar-fallback>
5 </x-avatar>
6
7 <x-avatar class="size-12 ring-1 ring-destructive/20">
8 <x-avatar-image src="https://github.com/maddex-avatar-missing.png" alt="@erin" />
9 <x-avatar-fallback class="bg-destructive/10 text-destructive">ER</x-avatar-fallback>
10 </x-avatar>
11
12 <x-avatar class="size-12 ring-1 ring-border">
13 <x-avatar-image src="https://github.com/maddex-qa-avatar-missing.png" alt="@qa" />
14 <x-avatar-fallback class="bg-secondary text-secondary-foreground">QA</x-avatar-fallback>
15 </x-avatar>
16</div>
Avatar Group
Layer Avatar instances with Tailwind utilities to preserve the shadcn group layout without introducing extra primitives.
Preview
CN
ML
ER
1<div class="flex items-center justify-center">
2 <div class="flex -space-x-3 rounded-full border bg-background p-1 shadow-sm">
3 <x-avatar class="size-11 border-2 border-background">
4 <x-avatar-image src="https://github.com/shadcn.png" alt="@shadcn" />
5 <x-avatar-fallback>CN</x-avatar-fallback>
6 </x-avatar>
7 <x-avatar class="size-11 border-2 border-background">
8 <x-avatar-image src="https://github.com/maxleiter.png" alt="@maxleiter" />
9 <x-avatar-fallback>ML</x-avatar-fallback>
10 </x-avatar>
11 <x-avatar class="size-11 border-2 border-background">
12 <x-avatar-image src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
13 <x-avatar-fallback>ER</x-avatar-fallback>
14 </x-avatar>
15 </div>
16</div>