🧑‍🎨 Avatar & Avatar Group

✨ Overview

The Avatar component represents a user or entity visually—commonly with an image, initials, or icon. The Avatar Group component helps you display multiple avatars together, optionally stacked or limited with overflow indication.

---

📦 Import

<!-- CDN -->
<link rel="stylesheet" href="path/to/avatar.css">

<!-- OR as part of your component library -->
@import "components/avatar.css";

---

🔹 Avatar

✅ Basic Usage

<div class="avatar">
  <img src="/users/john.jpg" alt="John Doe">
</div>

---

🖼 Variants

✅ With Initials

<div class="avatar">
  <span>JD</span>
</div>

✅ With Icon (SVG)

<div class="avatar">
  <svg viewBox="0 0 24 24" fill="currentColor">...</svg>
</div>

✅ With Badge

<div class="avatar badge">
  <img src="/users/john.jpg" alt="John Doe">
  <span class="badge-indicator online"></span>
</div>

---

🎨 Sizing

<div class="avatar avatar-sm">...</div>
<div class="avatar avatar-md">...</div>
<div class="avatar avatar-lg">...</div>

You can define custom sizes using CSS variables:

.avatar {
  --size: 48px;
}

---

⚙️ Styling & Responsiveness

.avatar img {
  max-width: 100%;
  height: auto;
  object-fit: cover;
  border-radius: 50%;
}

Supports theming with CSS variables like:

.avatar {
  background-color: var(--color-surface);
  border: 2px solid var(--fill);
}

---

🌒 Dark Mode Support

Add dark mode styling using CSS or media queries:

@media (prefers-color-scheme: dark) {
  .avatar {
    background-color: var(--color-surface-dark);
    border-color: var(--fill-dark);
  }
}

---

👥 Avatar Group

✅ Basic Usage

<div class="avatar-group">
  <div class="avatar"><img src="/u1.png" alt="Alice"></div>
  <div class="avatar"><img src="/u2.png" alt="Bob"></div>
  <div class="avatar"><img src="/u3.png" alt="Charlie"></div>
</div>

---

🔄 Stacked Layout

.avatar-group {
  display: flex;
}

.avatar-group .avatar {
  margin-left: -8px;
  border: 2px solid #fff;
  z-index: 1;
}

You can also use z-index to control overlap direction.

---

➕ Overflow Handling

<div class="avatar-group">
  <div class="avatar"><img src="/u1.png" alt="Alice"></div>
  <div class="avatar"><img src="/u2.png" alt="Bob"></div>
  <div class="avatar"><img src="/u3.png" alt="Charlie"></div>
  <div class="avatar avatar-overflow"><span>+3</span></div>
</div>

.avatar-overflow {
  background-color: #ddd;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
}

---

📌 Badge Positioning

Default is top-right. To customize:

.badge-indicator {
  position: absolute;
  top: 0;
  right: 0;
}

Change to bottom-left:

.badge-indicator {
  top: auto;
  right: auto;
  bottom: 0;
  left: 0;
}

---

🧠 Accessibility Tips

• Always include alt attributes on images.
• Use <span role="img" aria-label="JD"> for text-only avatars.
• Ensure color contrast for badges and backgrounds meets WCAG guidelines.

---

🧪 JavaScript Example (Dynamic Add/Remove)

const group = document.querySelector('.avatar-group');

function addAvatar(name, img) {
  const avatar = document.createElement('div');
  avatar.className = 'avatar';
  avatar.innerHTML = `<img src="${img}" alt="${name}">`;
  group.appendChild(avatar);
}

function clearAvatars() {
  group.innerHTML = '';
}

Absolutely! Let's go deeper into customizable styles for the Avatar and Avatar Group components so devs/designers can easily tweak the look and feel to match their brand or design system.

---

🎨 Customizable Styles

Here’s a full breakdown of how to style avatars using CSS variables, utility classes, or custom CSS—supporting light/dark themes, borders, shadows, sizes, shapes, and more.

---

🧩 1. CSS Variables (Recommended)

Set default styles in your component:

.avatar {
  --avatar-size: 48px;
  --avatar-border: 2px solid #fff;
  --avatar-radius: 50%;
  --avatar-shadow: 0 0 0 2px var(--fill);
  --avatar-bg: var(--color-surface);
  --avatar-color: #fff;

  width: var(--avatar-size);
  height: var(--avatar-size);
  border: var(--avatar-border);
  border-radius: var(--avatar-radius);
  box-shadow: var(--avatar-shadow);
  background-color: var(--avatar-bg);
  color: var(--avatar-color);
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
  overflow: hidden;
}

Then customize per instance:

<div
  class="avatar"
  style="--avatar-size: 64px; --avatar-border: none; --avatar-radius: 8px;">
  <img src="/me.png" alt="Me" />
</div>

---

🌀 2. Custom Shape

Change circular to rounded-square or even squircle:

.avatar.square {
  --avatar-radius: 8px;
}

.avatar.squircle {
  clip-path: path("M12 0C17.523 0 22 4.477 22 10C22 15.523 17.523 20 12 20C6.477 20 2 15.523 2 10C2 4.477 6.477 0 12 0Z");
}

---

🌗 3. Dark Mode Ready

.avatar {
  background-color: var(--color-surface, #f0f0f0);
}

@media (prefers-color-scheme: dark) {
  .avatar {
    background-color: var(--color-surface-dark, #1e1e1e);
    border-color: var(--fill-dark, #444);
  }
}

---

🧱 4. Utility Classes (Tailwind-like Example)

If using Tailwind or utility-first CSS:

<div class="w-12 h-12 rounded-full ring-2 ring-white bg-gray-200">
  <img src="/avatar.png" class="object-cover w-full h-full" alt="User" />
</div>

---

👥 5. Avatar Group Stacking/Spacing

Customize overlap and spacing:

.avatar-group .avatar {
  margin-left: -10px;
  border: 2px solid #fff;
  transition: transform 0.2s;
}
.avatar-group:hover .avatar {
  transform: scale(1.05);
}

Use z-index and hover states to make them interactive or re-order:

.avatar-group .avatar:hover {
  z-index: 10;
}

---

🧼 6. Badges & Indicators Customization

.avatar .badge-indicator {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  background-color: limegreen;
  position: absolute;
  top: 2px;
  right: 2px;
  border: 2px solid white;
}

/* Custom location */
.avatar[data-badge="bottom-left"] .badge-indicator {
  top: auto;
  left: 2px;
  bottom: 2px;
  right: auto;
}

Use data- attributes or extra classes to reposition easily.

---

🧩 CSS Custom Properties Summary

Variable	Description	Example
--avatar-size	Controls avatar dimensions	--avatar-size: 56px
--avatar-radius	Rounding (circle, square, etc.)	--avatar-radius: 12px
--avatar-border	Border width & color	--avatar-border: none
--avatar-shadow	Optional shadow	--avatar-shadow: 0 0 6px rgba(...)
--avatar-bg	Fallback bg when image fails	--avatar-bg: #eee
--avatar-color	Text/icon color	--avatar-color: #111

---

Would you like a live CodePen demo, CSS module export, or SCSS mixin version of this for your design system or team handoff? I can prep that too.