|$ curl https://forge-ai.dev/api/markdown?path=docs/components/avatar
$cat docs/avatars-&-user-images.md
updated Recently·20 min read·published

Avatars & User Images

CSSHTMLTailwindBootstrapUIIntermediate🎯Free Tools
Introduction

Avatars are compact visual identifiers for users, teams, and entities. This guide covers production-ready avatar patterns in plain HTML/CSS, Tailwind CSS, and Bootstrap — including images, initials, status dots, badges, groups, shapes, rings, and accessibility.

info

Always provide meaningful alt text for image avatars. For decorative avatars or initials, use an aria-label or hide the element from assistive technology with aria-hidden when redundant.
Basic Initials

Circular avatars with placeholder colors and initials — use when you don't have user photos.

basic-avatar
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar" style="background:#3B82F6">
3 JD
4 </div>
5 <div class="avatar" style="background:#A855F7">
6 AB
7 </div>
8 <div class="avatar" style="background:#22C55E">
9 KW
10 </div>
11 <div class="avatar" style="background:#F97316">
12 MR
13 </div>
14 <div class="avatar" style="background:#EF4444">
15 TS
16 </div>
17</div>
preview

info

Generate deterministic background colors from user names using a hash function. This ensures the same user always gets the same color across sessions without storing it.
Image Avatars

Avatars with actual user photos using a circular clip. Falls back to initials if the image fails to load.

image-avatar
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar img">
3 <img src="https://i.pravatar.cc/96?img=1" alt="User">
4 </div>
5 <div class="avatar img">
6 <img src="https://i.pravatar.cc/96?img=5" alt="User">
7 </div>
8 <div class="avatar img">
9 <img src="https://i.pravatar.cc/96?img=12" alt="User">
10 </div>
11 <div class="avatar initials" style="background:#606080">
12 AB
13 </div>
14 <div class="avatar img">
15 <img src="https://broken-url.invalid/photo.jpg" alt="User" onerror="this.style.display='none';this.nextElementSibling.style.display='flex'">
16 <span class="fallback" style="display:none;background:#EF4444">
17 EF
18 </span>
19 </div>
20</div>
preview
Sizes

From tiny 24px badges to large 64px profile avatars — scale to fit the context.

avatar-sizes
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar xs" style="background:#3B82F6">
3 JD
4 </div>
5 <div class="avatar sm" style="background:#A855F7">
6 AB
7 </div>
8 <div class="avatar md" style="background:#22C55E">
9 KW
10 </div>
11 <div class="avatar lg" style="background:#F97316">
12 MR
13 </div>
14 <div class="avatar xl" style="background:#EF4444">
15 TS
16 </div>
17</div>
preview
Status Indicators

Online, away, busy, and offline status dots on avatars — essential for chat and team apps.

avatar-status
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar-wrap">
3 <div class="avatar" style="background:#3B82F6">
4 JD
5 </div>
6 <span class="status online">
7 </span>
8 </div>
9 <div class="avatar-wrap">
10 <div class="avatar" style="background:#A855F7">
11 AB
12 </div>
13 <span class="status away">
14 </span>
15 </div>
16 <div class="avatar-wrap">
17 <div class="avatar" style="background:#22C55E">
18 KW
19 </div>
20 <span class="status busy">
21 </span>
22 </div>
23 <div class="avatar-wrap">
24 <div class="avatar" style="background:#606080">
25 MR
26 </div>
27 <span class="status offline">
28 </span>
29 </div>
30</div>
preview

best practice

Status indicators should have a 3px border matching the background color to create a clean separation from the avatar. Use semantic colors: green for online, yellow for away, red for busy, gray for offline.
Notification Badge

Avatars with a numeric badge count — perfect for unread messages or pending notifications.

avatar-badge
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar-wrap">
3 <div class="avatar" style="background:#3B82F6">
4 <img src="https://i.pravatar.cc/96?img=3" alt="">
5 </div>
6 <span class="badge">
7 3
8 </span>
9 </div>
10 <div class="avatar-wrap">
11 <div class="avatar" style="background:#A855F7">
12 AB
13 </div>
14 <span class="badge">
15 12
16 </span>
17 </div>
18 <div class="avatar-wrap">
19 <div class="avatar" style="background:#22C55E">
20 KW
21 </div>
22 <span class="badge dot">
23 </span>
24 </div>
25 <div class="avatar-wrap">
26 <div class="avatar" style="background:#606080">
27 MR
28 </div>
29 <span class="badge">
30 99+
31 </span>
32 </div>
33</div>
preview
Avatar Groups

Overlapping avatar stacks showing team members or collaborators with an overflow count.

avatar-group
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar-group">
3 <div class="avatar a1" style="background:#3B82F6">
4 JD
5 </div>
6 <div class="avatar a2" style="background:#A855F7">
7 AB
8 </div>
9 <div class="avatar a3" style="background:#22C55E">
10 KW
11 </div>
12 <div class="avatar a4" style="background:#F97316">
13 MR
14 </div>
15 <div class="avatar a5" style="background:#606080">
16 +5
17 </div>
18 </div>
19 <div class="avatar-group large">
20 <div class="avatar">
21 <img src="https://i.pravatar.cc/96?img=1" alt="">
22 </div>
23 <div class="avatar">
24 <img src="https://i.pravatar.cc/96?img=8" alt="">
25 </div>
26 <div class="avatar">
27 <img src="https://i.pravatar.cc/96?img=11" alt="">
28 </div>
29 <div class="avatar overflow">
30 +12
31 </div>
32 </div>
33</div>
preview
🔥

pro tip

For avatar groups, use negative margins to create the overlap effect. Always add a 3px border matching the background to separate overlapping avatars visually. Cap the visible count and show "+N" for the rest.
Shape Variants

Round, square, and rounded-square avatar shapes for different design contexts.

avatar-shapes
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar round" style="background:#3B82F6">
3 JD
4 </div>
5 <div class="avatar square" style="background:#A855F7">
6 AB
7 </div>
8 <div class="avatar rounded" style="background:#22C55E">
9 KW
10 </div>
11 <div class="avatar round" style="background:#F97316">
12 <img src="https://i.pravatar.cc/96?img=5" alt="">
13 </div>
14 <div class="avatar square" style="background:#EF4444">
15 <img src="https://i.pravatar.cc/96?img=9" alt="">
16 </div>
17</div>
preview
Ring & Bordered

Highlight active users, verified accounts, or selection state with colored rings and dashed borders.

avatar-ring
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar ring-green">
3 JD
4 </div>
5 <div class="avatar ring-blue">
6 AB
7 </div>
8 <div class="avatar ring-glow">
9 KW
10 </div>
11 <div class="avatar ring-dashed">
12 MR
13 </div>
14 <div class="avatar ring-white">
15 <img src="https://i.pravatar.cc/96?img=7" alt="">
16 </div>
17</div>
preview
Icon Avatars

Entity or team avatars built with inline SVG icons instead of initials or photos.

avatar-icon
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar team">
3 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="22" height="22">
4 <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/>
5 <circle cx="9" cy="7" r="4"/>
6 <path d="M23 21v-2a4 4 0 0 0-3-3.87"/>
7 <path d="M16 3.13a4 4 0 0 1 0 7.75"/>
8 </svg>
9 </div>
10 <div class="avatar bot">
11 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="22" height="22">
12 <rect x="3" y="11" width="18" height="10" rx="2"/>
13 <circle cx="12" cy="5" r="2"/>
14 <path d="M12 7v4"/>
15 <line x1="8" y1="16" x2="8" y2="16"/>
16 <line x1="16" y1="16" x2="16" y2="16"/>
17 </svg>
18 </div>
19 <div class="avatar org">
20 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="22" height="22">
21 <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>
22 <polyline points="9 22 9 12 15 12 15 22"/>
23 </svg>
24 </div>
25 <div class="avatar lock">
26 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="22" height="22">
27 <rect x="3" y="11" width="18" height="11" rx="2" ry="2"/>
28 <path d="M7 11V7a5 5 0 0 1 10 0v4"/>
29 </svg>
30 </div>
31</div>
preview
Avatar with Text

Avatars paired with name, role, and description — the building block of user lists and team pages.

avatar-text
Live
untitled.html
HTML
1<div class="list">
2 <div class="user-row">
3 <div class="avatar" style="background:#3B82F6">
4 <img src="https://i.pravatar.cc/96?img=1" alt="">
5 </div>
6 <div class="info">
7 <div class="name">
8 Jane Doe
9 </div>
10 <div class="role">
11 Engineering Lead
12 </div>
13 </div>
14 <button class="follow-btn">
15 Follow
16 </button>
17 </div>
18 <div class="user-row">
19 <div class="avatar" style="background:#A855F7">
20 AB
21 </div>
22 <div class="info">
23 <div class="name">
24 Alex Brown
25 </div>
26 <div class="role">
27 Product Designer
28 </div>
29 </div>
30 <button class="follow-btn active">
31 Following
32 </button>
33 </div>
34 <div class="user-row">
35 <div class="avatar" style="background:#22C55E">
36 KW
37 </div>
38 <div class="info">
39 <div class="name">
40 Kim West
41 </div>
42 <div class="role">
43 DevOps Engineer
44 </div>
45 </div>
46 <button class="follow-btn">
47 Follow
48 </button>
49 </div>
50</div>
preview
📝

note

When pairing avatars with text, maintain consistent spacing and vertical alignment. The avatar should align with the first line of text, not vertically center the entire text block.
Loading Skeleton

Skeleton placeholder avatars while user data is loading — matches the final avatar shape and size.

avatar-skeleton
Live
untitled.html
HTML
1<div class="wrap">
2 <div class="avatar skeleton">
3 </div>
4 <div class="avatar skeleton">
5 </div>
6 <div class="avatar skeleton">
7 </div>
8 <div class="avatar skeleton lg">
9 </div>
10 <div class="avatar skeleton">
11 </div>
12</div>
13<div class="row">
14 <div class="avatar skeleton">
15 </div>
16 <div class="lines">
17 <div class="line skeleton">
18 </div>
19 <div class="line skeleton short">
20 </div>
21 </div>
22</div>
preview

info

Skeleton avatars should match the exact dimensions of the real avatars they replace. This prevents layout shift when content loads. Include skeleton text lines next to skeleton avatars for a complete placeholder.
Accessibility

Avatars are often small and visually rich, so they need explicit accessible names and robust fallbacks.

  • Image avatars must have meaningful alt text or an aria-label on the wrapper.
  • Initial avatars should include visually hidden text or an aria-label with the full user name.
  • Status indicators need aria-label descriptions like "Jane Doe is online" or be exposed as part of the avatar label.
  • Use real <img> elements with onerror fallbacks, not background images, so failures are detectable.
  • Ensure color contrast between initials and background meets WCAG AA (4.5:1).
  • Keep avatars focusable only when they are interactive; decorative avatars should not be in the tab order.

Community

Get help on Slack, Discord or VIP

Stuck on a guide? Join the community and ask.