|$ curl https://forge-ai.dev/api/markdown?path=docs/components/avatar
$cat docs/avatars-&-user-images.md
updated Recently·11 min read·published
Avatars & User Images
User avatars with images, initials, status indicators, grouped stacks, placeholder shapes, and size variants.
Basic Avatars
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:12px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar { |
| 9 | width:44px; |
| 10 | height:44px; |
| 11 | border-radius:50%; |
| 12 | display:flex; |
| 13 | align-items:center; |
| 14 | justify-content:center; |
| 15 | font-size:14px; |
| 16 | font-weight:700; |
| 17 | color:#fff; |
| 18 | font-family:system-ui, |
| 19 | sans-serif; |
| 20 | user-select:none; |
| 21 | flex-shrink:0 |
| 22 | } |
ℹ
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:12px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar { |
| 9 | width:48px; |
| 10 | height:48px; |
| 11 | border-radius:50%; |
| 12 | overflow:hidden; |
| 13 | flex-shrink:0; |
| 14 | display:flex; |
| 15 | align-items:center; |
| 16 | justify-content:center; |
| 17 | font-size:15px; |
| 18 | font-weight:700; |
| 19 | color:#fff; |
| 20 | font-family:system-ui, |
| 21 | sans-serif |
| 22 | } |
| 23 | .avatar.img img { |
| 24 | width:100%; |
| 25 | height:100%; |
| 26 | object-fit:cover |
| 27 | } |
| 28 | .avatar.initials { |
| 29 | background:#606080 |
| 30 | } |
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:14px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar { |
| 9 | border-radius:50%; |
| 10 | display:flex; |
| 11 | align-items:center; |
| 12 | justify-content:center; |
| 13 | font-weight:700; |
| 14 | color:#fff; |
| 15 | font-family:system-ui, |
| 16 | sans-serif; |
| 17 | flex-shrink:0 |
| 18 | } |
| 19 | .xs { |
| 20 | width:24px; |
| 21 | height:24px; |
| 22 | font-size:9px |
| 23 | } |
| 24 | .sm { |
| 25 | width:32px; |
| 26 | height:32px; |
| 27 | font-size:11px |
| 28 | } |
| 29 | .md { |
| 30 | width:44px; |
| 31 | height:44px; |
| 32 | font-size:14px |
| 33 | } |
| 34 | .lg { |
| 35 | width:56px; |
| 36 | height:56px; |
| 37 | font-size:18px |
| 38 | } |
| 39 | .xl { |
| 40 | width:72px; |
| 41 | height:72px; |
| 42 | font-size:22px |
| 43 | } |
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:24px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar-wrap { |
| 9 | position:relative; |
| 10 | flex-shrink:0 |
| 11 | } |
| 12 | .avatar { |
| 13 | width:48px; |
| 14 | height:48px; |
| 15 | border-radius:50%; |
| 16 | display:flex; |
| 17 | align-items:center; |
| 18 | justify-content:center; |
| 19 | font-size:15px; |
| 20 | font-weight:700; |
| 21 | color:#fff; |
| 22 | font-family:system-ui, |
| 23 | sans-serif |
| 24 | } |
| 25 | .status { |
| 26 | position:absolute; |
| 27 | bottom:0; |
| 28 | right:0; |
| 29 | width:14px; |
| 30 | height:14px; |
| 31 | border-radius:50%; |
| 32 | border:3px solid #0D0D0D; |
| 33 | box-sizing:content-box |
| 34 | } |
| 35 | .online { |
| 36 | background:#22C55E |
| 37 | } |
| 38 | .away { |
| 39 | background:#EAB308 |
| 40 | } |
| 41 | .busy { |
| 42 | background:#EF4444 |
| 43 | } |
| 44 | .offline { |
| 45 | background:#606080 |
| 46 | } |
✓
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:24px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar-wrap { |
| 9 | position:relative; |
| 10 | flex-shrink:0 |
| 11 | } |
| 12 | .avatar { |
| 13 | width:48px; |
| 14 | height:48px; |
| 15 | border-radius:50%; |
| 16 | display:flex; |
| 17 | align-items:center; |
| 18 | justify-content:center; |
| 19 | font-size:15px; |
| 20 | font-weight:700; |
| 21 | color:#fff; |
| 22 | font-family:system-ui, |
| 23 | sans-serif; |
| 24 | overflow:hidden |
| 25 | } |
| 26 | .avatar img { |
| 27 | width:100%; |
| 28 | height:100%; |
| 29 | object-fit:cover |
| 30 | } |
| 31 | .badge { |
| 32 | position:absolute; |
| 33 | top:-4px; |
| 34 | right:-4px; |
| 35 | min-width:20px; |
| 36 | height:20px; |
| 37 | border-radius:10px; |
| 38 | background:#EF4444; |
| 39 | color:#fff; |
| 40 | font-size:10px; |
| 41 | font-weight:700; |
| 42 | display:flex; |
| 43 | align-items:center; |
| 44 | justify-content:center; |
| 45 | padding:0 5px; |
| 46 | border:2px solid #0D0D0D; |
| 47 | font-family:monospace; |
| 48 | box-sizing:content-box |
| 49 | } |
| 50 | .badge.dot { |
| 51 | width:12px; |
| 52 | height:12px; |
| 53 | min-width:12px; |
| 54 | padding:0; |
| 55 | top:0; |
| 56 | right:0 |
| 57 | } |
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | flex-direction:column; |
| 4 | gap:20px; |
| 5 | align-items:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar-group { |
| 9 | display:flex |
| 10 | } |
| 11 | .avatar-group .avatar { |
| 12 | width:40px; |
| 13 | height:40px; |
| 14 | border-radius:50%; |
| 15 | display:flex; |
| 16 | align-items:center; |
| 17 | justify-content:center; |
| 18 | font-size:13px; |
| 19 | font-weight:700; |
| 20 | color:#fff; |
| 21 | font-family:system-ui, |
| 22 | sans-serif; |
| 23 | border:3px solid #0D0D0D; |
| 24 | overflow:hidden; |
| 25 | margin-left:-10px |
| 26 | } |
| 27 | .avatar-group .avatar:first-child { |
| 28 | margin-left:0 |
| 29 | } |
| 30 | .avatar-group .avatar img { |
| 31 | width:100%; |
| 32 | height:100%; |
| 33 | object-fit:cover |
| 34 | } |
| 35 | .avatar-group.large .avatar { |
| 36 | width:48px; |
| 37 | height:48px; |
| 38 | font-size:15px; |
| 39 | margin-left:-12px |
| 40 | } |
| 41 | .avatar-group.large .avatar:first-child { |
| 42 | margin-left:0 |
| 43 | } |
| 44 | .avatar.overflow { |
| 45 | background:#1A1A2E; |
| 46 | color:#A0A0A0; |
| 47 | font-size:12px; |
| 48 | border-color:#0D0D0D |
| 49 | } |
🔥
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> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:14px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:32px |
| 7 | } |
| 8 | .avatar { |
| 9 | width:52px; |
| 10 | height:52px; |
| 11 | display:flex; |
| 12 | align-items:center; |
| 13 | justify-content:center; |
| 14 | font-size:16px; |
| 15 | font-weight:700; |
| 16 | color:#fff; |
| 17 | font-family:system-ui, |
| 18 | sans-serif; |
| 19 | overflow:hidden; |
| 20 | flex-shrink:0 |
| 21 | } |
| 22 | .avatar img { |
| 23 | width:100%; |
| 24 | height:100%; |
| 25 | object-fit:cover |
| 26 | } |
| 27 | .round { |
| 28 | border-radius:50% |
| 29 | } |
| 30 | .square { |
| 31 | border-radius:8px |
| 32 | } |
| 33 | .rounded { |
| 34 | border-radius:16px |
| 35 | } |
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> |
untitled.css
CSS
| 1 | .list { |
| 2 | max-width:380px; |
| 3 | margin:16px auto; |
| 4 | display:flex; |
| 5 | flex-direction:column |
| 6 | } |
| 7 | .user-row { |
| 8 | display:flex; |
| 9 | align-items:center; |
| 10 | gap:12px; |
| 11 | padding:12px 16px; |
| 12 | border-bottom:1px solid #1A1A2E; |
| 13 | transition:background .2s |
| 14 | } |
| 15 | .user-row:hover { |
| 16 | background:rgba(255, |
| 17 | 255, |
| 18 | 255, |
| 19 | .02) |
| 20 | } |
| 21 | .avatar { |
| 22 | width:40px; |
| 23 | height:40px; |
| 24 | border-radius:50%; |
| 25 | display:flex; |
| 26 | align-items:center; |
| 27 | justify-content:center; |
| 28 | font-size:14px; |
| 29 | font-weight:700; |
| 30 | color:#fff; |
| 31 | flex-shrink:0; |
| 32 | overflow:hidden |
| 33 | } |
| 34 | .avatar img { |
| 35 | width:100%; |
| 36 | height:100%; |
| 37 | object-fit:cover |
| 38 | } |
| 39 | .info { |
| 40 | flex:1; |
| 41 | min-width:0 |
| 42 | } |
| 43 | .name { |
| 44 | font-size:13px; |
| 45 | color:#E0E0E0; |
| 46 | font-weight:500 |
| 47 | } |
| 48 | .role { |
| 49 | font-size:11px; |
| 50 | color:#606080; |
| 51 | margin-top:1px |
| 52 | } |
| 53 | .follow-btn { |
| 54 | padding:6px 14px; |
| 55 | border-radius:6px; |
| 56 | font-size:11px; |
| 57 | font-weight:600; |
| 58 | cursor:pointer; |
| 59 | border:1px solid #2A2A3E; |
| 60 | background:transparent; |
| 61 | color:#A0A0A0; |
| 62 | transition:all .2s; |
| 63 | flex-shrink:0 |
| 64 | } |
| 65 | .follow-btn:hover { |
| 66 | border-color:#3B82F6; |
| 67 | color:#3B82F6 |
| 68 | } |
| 69 | .follow-btn.active { |
| 70 | background:#3B82F6; |
| 71 | border-color:#3B82F6; |
| 72 | color:#fff |
| 73 | } |
📝
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> |
| 23 | </div> |
untitled.css
CSS
| 1 | .wrap { |
| 2 | display:flex; |
| 3 | gap:12px; |
| 4 | align-items:center; |
| 5 | justify-content:center; |
| 6 | padding:24px 32px 8px |
| 7 | } |
| 8 | .row { |
| 9 | display:flex; |
| 10 | gap:12px; |
| 11 | align-items:center; |
| 12 | justify-content:center; |
| 13 | padding:8px 32px 24px |
| 14 | } |
| 15 | .avatar { |
| 16 | width:44px; |
| 17 | height:44px; |
| 18 | border-radius:50%; |
| 19 | flex-shrink:0 |
| 20 | } |
| 21 | .avatar.lg { |
| 22 | width:56px; |
| 23 | height:56px |
| 24 | } |
| 25 | .lines { |
| 26 | display:flex; |
| 27 | flex-direction:column; |
| 28 | gap:8px |
| 29 | } |
| 30 | .line { |
| 31 | height:12px; |
| 32 | border-radius:6px; |
| 33 | width:120px |
| 34 | } |
| 35 | .line.short { |
| 36 | width:80px |
| 37 | } |
| 38 | .skeleton { |
| 39 | background:linear-gradient(90deg, |
| 40 | #1A1A2E 25%, |
| 41 | #2A2A3E 50%, |
| 42 | #1A1A2E 75%); |
| 43 | background-size:200% 100%; |
| 44 | animation:shimmer 1.5s ease-in-out infinite |
| 45 | } |
| 46 | @keyframes shimmer { |
| 47 | 0% { |
| 48 | background-position:200% 0 |
| 49 | } |
| 50 | 100% { |
| 51 | background-position:-200% 0 |
| 52 | } |
| 53 | } |
ℹ
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.