Avatar

Experimental Alpha

This library is a work-in-progress. We are releasing it early to gather feedback, but it is not ready for production.

Avatar components are used to represent users or entities in your application. They can display profile images, initials, or icons, and support multiple sizes, shapes, and color variants.

Examples

Vue

Lit

React

Live Preview

Text Initials

With Images

Sizes

Shapes

Variants

With Icons

Avatar Groups

Group multiple avatars together to represent teams, collaborators, or participants.

Text Avatars

Image Avatars

Mixed Content

Different Sizes

With Variants

Avatar Group Custom Styling

Use CSS Shadow Parts to customize avatar group layouts and effects.

Custom Spacing (No Overlap)

Enhanced Hover Effects

CSS Shadow Parts Customization

Use CSS Shadow Parts to customize the avatar's appearance without affecting the component's internal styling. The following are meant solely to show how to utilize CSS shadow parts to create custom avatar styles. They are NOT meant to represent best practices or good taste in avatar design!

View Vue Code

<template>
  <section>
    <div class="mbe4">
      <h2>Text Initials</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar text="AB" />
      <VueAvatar text="CD" />
      <VueAvatar text="EF" />
      <VueAvatar text="GH" />
    </div>

    <div class="mbe4">
      <h2>With Images</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar
        img-src="https://i.pravatar.cc/150?img=1"
        img-alt="User 1"
      />
      <VueAvatar
        img-src="https://i.pravatar.cc/150?img=2"
        img-alt="User 2"
      />
      <VueAvatar
        img-src="https://i.pravatar.cc/150?img=3"
        img-alt="User 3"
      />
      <VueAvatar
        img-src="https://i.pravatar.cc/150?img=4"
        img-alt="User 4"
      />
    </div>

    <div class="mbe4">
      <h2>Sizes</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar
        text="XS"
        size="xs"
      />
      <VueAvatar
        text="SM"
        size="sm"
      />
      <VueAvatar
        text="MD"
        size="md"
      />
      <VueAvatar
        text="LG"
        size="lg"
      />
      <VueAvatar
        text="XL"
        size="xl"
      />
    </div>

    <div class="mbe4">
      <h2>Shapes</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar
        text="AB"
        shape="circle"
      />
      <VueAvatar
        text="CD"
        shape="square"
      />
      <VueAvatar
        text="EF"
        shape="rounded"
      />
    </div>

    <div class="mbe4">
      <h2>Variants</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar
        text="DF"
        variant="default"
      />
      <VueAvatar
        text="IN"
        variant="info"
      />
      <VueAvatar
        text="WN"
        variant="warning"
      />
      <VueAvatar
        text="SC"
        variant="success"
      />
      <VueAvatar
        text="ER"
        variant="error"
      />
      <VueAvatar
        text="MC"
        variant="monochrome"
      />
    </div>

    <div class="mbe4">
      <h2>With Icons</h2>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar>
        <User :size="24" />
      </VueAvatar>
      <VueAvatar size="lg">
        <UserCircle :size="32" />
      </VueAvatar>
      <VueAvatar variant="info">
        <Mail :size="24" />
      </VueAvatar>
      <VueAvatar variant="success">
        <Check :size="24" />
      </VueAvatar>
    </div>

    <div class="mbe4">
      <h2>Avatar Groups</h2>
      <p class="mbs2 mbe3">
        Group multiple avatars together to represent teams, collaborators, or participants.
      </p>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Text Avatars</h2>
      <VueAvatarGroup class="avatar-group-bordered">
        <VueAvatar
          text="AB"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="CD"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="EF"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="GH"
          variant="info"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Image Avatars</h2>
      <VueAvatarGroup class="avatar-group-bordered">
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=1"
          img-alt="User 1"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=2"
          img-alt="User 2"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=3"
          img-alt="User 3"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=4"
          img-alt="User 4"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=5"
          img-alt="User 5"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Mixed Content</h2>
      <VueAvatarGroup class="avatar-group-bordered">
        <VueAvatar
          text="AB"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="RL"
          variant="info"
          size="lg"
        />
        <VueAvatar size="lg">
          <User :size="24" />
        </VueAvatar>
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=10"
          img-alt="User 1"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=11"
          img-alt="User 2"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Different Sizes</h2>
      <div class="stacked-mobile mbe3">
        <VueAvatarGroup class="avatar-group-bordered">
          <VueAvatar
            text="SM"
            size="sm"
          />
          <VueAvatar
            text="SM"
            size="sm"
          />
          <VueAvatar
            text="SM"
            size="sm"
          />
        </VueAvatarGroup>
      </div>
      <div class="stacked-mobile mbe3">
        <VueAvatarGroup class="avatar-group-bordered">
          <VueAvatar
            text="MD"
            size="md"
          />
          <VueAvatar
            text="MD"
            size="md"
          />
          <VueAvatar
            text="MD"
            size="md"
          />
        </VueAvatarGroup>
      </div>
      <div class="stacked-mobile">
        <VueAvatarGroup class="avatar-group-bordered">
          <VueAvatar
            text="XL"
            size="xl"
          />
          <VueAvatar
            text="XL"
            size="xl"
          />
          <VueAvatar
            text="XL"
            size="xl"
          />
        </VueAvatarGroup>
      </div>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">With Variants</h2>
      <VueAvatarGroup class="avatar-group-bordered">
        <VueAvatar
          text="DF"
          variant="default"
          size="lg"
        />
        <VueAvatar
          text="IN"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="WN"
          variant="warning"
          size="lg"
        />
        <VueAvatar
          text="SC"
          variant="success"
          size="lg"
        />
        <VueAvatar
          text="ER"
          variant="error"
          size="lg"
        />
        <VueAvatar
          text="MC"
          variant="monochrome"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2>Avatar Group Custom Styling</h2>
      <p class="mbs2 mbe3">
        Use CSS Shadow Parts to customize avatar group layouts and effects.
      </p>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Custom Spacing (No Overlap)</h2>
      <VueAvatarGroup class="custom-avatar-group">
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=20"
          img-alt="User 1"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=21"
          img-alt="User 2"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=22"
          img-alt="User 3"
          size="lg"
        />
        <VueAvatar
          img-src="https://i.pravatar.cc/150?img=23"
          img-alt="User 4"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2 class="mbe2">Enhanced Hover Effects</h2>
      <VueAvatarGroup class="stacked-group">
        <VueAvatar
          text="AB"
          variant="info"
          size="lg"
        />
        <VueAvatar
          text="CD"
          variant="success"
          size="lg"
        />
        <VueAvatar
          text="EF"
          variant="warning"
          size="lg"
        />
        <VueAvatar
          text="GH"
          variant="error"
          size="lg"
        />
      </VueAvatarGroup>
    </div>

    <div class="mbe4">
      <h2>CSS Shadow Parts Customization</h2>
      <p class="mbs2 mbe3">
        Use CSS Shadow Parts to customize the avatar's appearance without
        affecting the component's internal styling. The following are meant
        solely to show how to utilize CSS shadow parts to create custom avatar
        styles. They are NOT meant to represent best practices or good taste in
        avatar design!
      </p>
    </div>
    <div class="stacked-mobile mbe4">
      <VueAvatar
        class="custom-avatar-gradient"
        text="GR"
      />
      <VueAvatar
        class="custom-avatar-border"
        img-src="https://i.pravatar.cc/150?img=8"
        img-alt="Custom border"
      />
    </div>
  </section>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { VueAvatar, VueAvatarGroup } from "agnosticui-core/avatar/vue";
import { User, UserCircle, Mail, Check } from "lucide-vue-next";

export default defineComponent({
  name: "AvatarExamples",
  components: {
    VueAvatar,
    VueAvatarGroup,
    User,
    UserCircle,
    Mail,
    Check,
  },
});
</script>

<style>
/* Avatar Group base styling */
.avatar-group-bordered ag-avatar::part(ag-avatar) {
  border: 2px solid white;
}

/* CSS Shadow Parts customization examples */
.custom-avatar-gradient::part(ag-avatar) {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border: 3px solid #fff;
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);
  font-weight: 700;
}

.custom-avatar-border::part(ag-avatar) {
  border: 4px solid #10b981;
  box-shadow: 0 0 0 4px rgba(16, 185, 129, 0.2);
}

/* Avatar Group custom styling examples */
.custom-avatar-group::part(ag-avatar-group) {
  gap: 0.5rem;
}

.custom-avatar-group ag-avatar::part(ag-avatar) {
  border: 3px solid #fff;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

.custom-avatar-group ag-avatar:not(:first-child) {
  margin-inline-start: 0;
}

.stacked-group ag-avatar::part(ag-avatar) {
  border: 3px solid #10b981;
}

.stacked-group ag-avatar {
  transition: all 0.3s ease;
}

.stacked-group ag-avatar:hover {
  transform: translateY(-8px) scale(1.1);
  z-index: 100 !important;
}
</style>

Live Preview

View Lit / Web Component Code

import { LitElement, html, svg } from 'lit';
import 'agnosticui-core/avatar';

export class AvatarLitExamples extends LitElement {
  // Render in light DOM to access global utility classes
  createRenderRoot() {
    return this;
  }

  // Helper method for User icon SVG
  userIcon(size = 24) {
    return svg`
      <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2" />
        <circle cx="12" cy="7" r="4" />
      </svg>
    `;
  }

  // Helper method for UserCircle icon SVG
  userCircleIcon(size = 24) {
    return svg`
      <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <circle cx="12" cy="12" r="10" />
        <circle cx="12" cy="10" r="3" />
        <path d="M7 20.662V19a2 2 0 0 1 2-2h6a2 2 0 0 1 2 2v1.662" />
      </svg>
    `;
  }

  // Helper method for Mail icon SVG
  mailIcon(size = 24) {
    return svg`
      <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <rect width="20" height="16" x="2" y="4" rx="2" />
        <path d="m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7" />
      </svg>
    `;
  }

  // Helper method for Check icon SVG
  checkIcon(size = 24) {
    return svg`
      <svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
        <path d="M20 6 9 17l-5-5" />
      </svg>
    `;
  }

  render() {
    return html`
      <section>
        <div class="mbe4">
          <h2>Text Initials</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar text="AB"></ag-avatar>
          <ag-avatar text="CD"></ag-avatar>
          <ag-avatar text="EF"></ag-avatar>
          <ag-avatar text="GH"></ag-avatar>
        </div>

        <div class="mbe4">
          <h2>With Images</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar
            img-src="https://i.pravatar.cc/150?img=1"
            img-alt="User 1"
          ></ag-avatar>
          <ag-avatar
            img-src="https://i.pravatar.cc/150?img=2"
            img-alt="User 2"
          ></ag-avatar>
          <ag-avatar
            img-src="https://i.pravatar.cc/150?img=3"
            img-alt="User 3"
          ></ag-avatar>
          <ag-avatar
            img-src="https://i.pravatar.cc/150?img=4"
            img-alt="User 4"
          ></ag-avatar>
        </div>

        <div class="mbe4">
          <h2>Sizes</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar text="XS" size="xs"></ag-avatar>
          <ag-avatar text="SM" size="sm"></ag-avatar>
          <ag-avatar text="MD" size="md"></ag-avatar>
          <ag-avatar text="LG" size="lg"></ag-avatar>
          <ag-avatar text="XL" size="xl"></ag-avatar>
        </div>

        <div class="mbe4">
          <h2>Shapes</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar text="AB" shape="circle"></ag-avatar>
          <ag-avatar text="CD" shape="square"></ag-avatar>
          <ag-avatar text="EF" shape="rounded"></ag-avatar>
        </div>

        <div class="mbe4">
          <h2>Variants</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar text="DF" variant="default"></ag-avatar>
          <ag-avatar text="IN" variant="info"></ag-avatar>
          <ag-avatar text="WN" variant="warning"></ag-avatar>
          <ag-avatar text="SC" variant="success"></ag-avatar>
          <ag-avatar text="ER" variant="error"></ag-avatar>
          <ag-avatar text="MC" variant="monochrome"></ag-avatar>
        </div>

        <div class="mbe4">
          <h2>With Icons</h2>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar>
            ${this.userIcon(24)}
          </ag-avatar>
          <ag-avatar size="lg">
            ${this.userCircleIcon(32)}
          </ag-avatar>
          <ag-avatar variant="info">
            ${this.mailIcon(24)}
          </ag-avatar>
          <ag-avatar variant="success">
            ${this.checkIcon(24)}
          </ag-avatar>
        </div>

        <div class="mbe4">
          <h2>Avatar Groups</h2>
          <p class="mbs2 mbe3">
            Group multiple avatars together to represent teams, collaborators, or participants.
          </p>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Text Avatars</h2>
          <ag-avatar-group class="avatar-group-bordered">
            <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="CD" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="EF" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="GH" variant="info" size="lg"></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Image Avatars</h2>
          <ag-avatar-group class="avatar-group-bordered">
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=1"
              img-alt="User 1"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=2"
              img-alt="User 2"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=3"
              img-alt="User 3"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=4"
              img-alt="User 4"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=5"
              img-alt="User 5"
              size="lg"
            ></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Mixed Content</h2>
          <ag-avatar-group class="avatar-group-bordered">
            <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="RL" variant="info" size="lg"></ag-avatar>
            <ag-avatar size="lg">
              ${this.userIcon(24)}
            </ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=10"
              img-alt="User 1"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=11"
              img-alt="User 2"
              size="lg"
            ></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Different Sizes</h2>
          <div class="stacked-mobile mbe3">
            <ag-avatar-group class="avatar-group-bordered">
              <ag-avatar text="SM" size="sm"></ag-avatar>
              <ag-avatar text="SM" size="sm"></ag-avatar>
              <ag-avatar text="SM" size="sm"></ag-avatar>
            </ag-avatar-group>
          </div>
          <div class="stacked-mobile mbe3">
            <ag-avatar-group class="avatar-group-bordered">
              <ag-avatar text="MD" size="md"></ag-avatar>
              <ag-avatar text="MD" size="md"></ag-avatar>
              <ag-avatar text="MD" size="md"></ag-avatar>
            </ag-avatar-group>
          </div>
          <div class="stacked-mobile">
            <ag-avatar-group class="avatar-group-bordered">
              <ag-avatar text="XL" size="xl"></ag-avatar>
              <ag-avatar text="XL" size="xl"></ag-avatar>
              <ag-avatar text="XL" size="xl"></ag-avatar>
            </ag-avatar-group>
          </div>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">With Variants</h2>
          <ag-avatar-group class="avatar-group-bordered">
            <ag-avatar text="DF" variant="default" size="lg"></ag-avatar>
            <ag-avatar text="IN" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="WN" variant="warning" size="lg"></ag-avatar>
            <ag-avatar text="SC" variant="success" size="lg"></ag-avatar>
            <ag-avatar text="ER" variant="error" size="lg"></ag-avatar>
            <ag-avatar text="MC" variant="monochrome" size="lg"></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2>Avatar Group Custom Styling</h2>
          <p class="mbs2 mbe3">
            Use CSS Shadow Parts to customize avatar group layouts and effects.
          </p>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Custom Spacing (No Overlap)</h2>
          <ag-avatar-group class="custom-avatar-group">
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=20"
              img-alt="User 1"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=21"
              img-alt="User 2"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=22"
              img-alt="User 3"
              size="lg"
            ></ag-avatar>
            <ag-avatar
              img-src="https://i.pravatar.cc/150?img=23"
              img-alt="User 4"
              size="lg"
            ></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2 class="mbe2">Enhanced Hover Effects</h2>
          <ag-avatar-group class="stacked-group">
            <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
            <ag-avatar text="CD" variant="success" size="lg"></ag-avatar>
            <ag-avatar text="EF" variant="warning" size="lg"></ag-avatar>
            <ag-avatar text="GH" variant="error" size="lg"></ag-avatar>
          </ag-avatar-group>
        </div>

        <div class="mbe4">
          <h2>CSS Shadow Parts Customization</h2>
          <p class="mbs2 mbe3">
            Use CSS Shadow Parts to customize the avatar's appearance without
            affecting the component's internal styling. The following are meant
            solely to show how to utilize CSS shadow parts to create custom avatar
            styles. They are NOT meant to represent best practices or good taste in
            avatar design!
          </p>
        </div>
        <div class="stacked-mobile mbe4">
          <ag-avatar class="custom-avatar-gradient" text="GR"></ag-avatar>
          <ag-avatar
            class="custom-avatar-border"
            img-src="https://i.pravatar.cc/150?img=8"
            img-alt="Custom border"
          ></ag-avatar>
        </div>

        <style>
          /* Avatar Group base styling */
          .avatar-group-bordered ag-avatar::part(ag-avatar) {
            border: 2px solid white;
          }

          /* CSS Shadow Parts customization examples */
          .custom-avatar-gradient::part(ag-avatar) {
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            color: white;
            border: 3px solid #fff;
            box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);
            font-weight: 700;
          }

          .custom-avatar-border::part(ag-avatar) {
            border: 4px solid #10b981;
            box-shadow: 0 0 0 4px rgba(16, 185, 129, 0.2);
          }

          /* Avatar Group custom styling examples */
          .custom-avatar-group::part(ag-avatar-group) {
            gap: 0.5rem;
          }

          .custom-avatar-group ag-avatar::part(ag-avatar) {
            border: 3px solid #fff;
            box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
          }

          .custom-avatar-group ag-avatar:not(:first-child) {
            margin-inline-start: 0;
          }

          .stacked-group ag-avatar::part(ag-avatar) {
            border: 3px solid #10b981;
          }

          .stacked-group ag-avatar {
            transition: all 0.3s ease;
          }

          .stacked-group ag-avatar:hover {
            transform: translateY(-8px) scale(1.1);
            z-index: 100 !important;
          }
        </style>
      </section>
    `;
  }
}

customElements.define('avatar-lit-examples', AvatarLitExamples);

Interactive Preview: Click the "Open in StackBlitz" button below to see this example running live in an interactive playground.

View React Code

import { ReactAvatar, ReactAvatarGroup } from "agnosticui-core/avatar/react";
import { User, UserCircle, Mail, Check } from "lucide-react";

export default function AvatarReactExamples() {
  return (
    <section>
      <div className="mbe4">
        <h2>Text Initials</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar text="AB" />
        <ReactAvatar text="CD" />
        <ReactAvatar text="EF" />
        <ReactAvatar text="GH" />
      </div>

      <div className="mbe4">
        <h2>With Images</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar
          imgSrc="https://i.pravatar.cc/150?img=1"
          imgAlt="User 1"
        />
        <ReactAvatar
          imgSrc="https://i.pravatar.cc/150?img=2"
          imgAlt="User 2"
        />
        <ReactAvatar
          imgSrc="https://i.pravatar.cc/150?img=3"
          imgAlt="User 3"
        />
        <ReactAvatar
          imgSrc="https://i.pravatar.cc/150?img=4"
          imgAlt="User 4"
        />
      </div>

      <div className="mbe4">
        <h2>Sizes</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar text="XS" size="xs" />
        <ReactAvatar text="SM" size="sm" />
        <ReactAvatar text="MD" size="md" />
        <ReactAvatar text="LG" size="lg" />
        <ReactAvatar text="XL" size="xl" />
      </div>

      <div className="mbe4">
        <h2>Shapes</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar text="AB" shape="circle" />
        <ReactAvatar text="CD" shape="square" />
        <ReactAvatar text="EF" shape="rounded" />
      </div>

      <div className="mbe4">
        <h2>Variants</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar text="DF" variant="default" />
        <ReactAvatar text="IN" variant="info" />
        <ReactAvatar text="WN" variant="warning" />
        <ReactAvatar text="SC" variant="success" />
        <ReactAvatar text="ER" variant="error" />
        <ReactAvatar text="MC" variant="monochrome" />
      </div>

      <div className="mbe4">
        <h2>With Icons</h2>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar>
          <User size={24} />
        </ReactAvatar>
        <ReactAvatar size="lg">
          <UserCircle size={32} />
        </ReactAvatar>
        <ReactAvatar variant="info">
          <Mail size={24} />
        </ReactAvatar>
        <ReactAvatar variant="success">
          <Check size={24} />
        </ReactAvatar>
      </div>

      <div className="mbe4">
        <h2>Avatar Groups</h2>
        <p className="mbs2 mbe3">
          Group multiple avatars together to represent teams, collaborators, or participants.
        </p>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Text Avatars</h2>
        <ReactAvatarGroup className="avatar-group-bordered">
          <ReactAvatar text="AB" variant="info" size="lg" />
          <ReactAvatar text="CD" variant="info" size="lg" />
          <ReactAvatar text="EF" variant="info" size="lg" />
          <ReactAvatar text="GH" variant="info" size="lg" />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Image Avatars</h2>
        <ReactAvatarGroup className="avatar-group-bordered">
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=1"
            imgAlt="User 1"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=2"
            imgAlt="User 2"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=3"
            imgAlt="User 3"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=4"
            imgAlt="User 4"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=5"
            imgAlt="User 5"
            size="lg"
          />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Mixed Content</h2>
        <ReactAvatarGroup className="avatar-group-bordered">
          <ReactAvatar text="AB" variant="info" size="lg" />
          <ReactAvatar text="RL" variant="info" size="lg" />
          <ReactAvatar size="lg">
            <User size={24} />
          </ReactAvatar>
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=10"
            imgAlt="User 1"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=11"
            imgAlt="User 2"
            size="lg"
          />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Different Sizes</h2>
        <div className="stacked-mobile mbe3">
          <ReactAvatarGroup className="avatar-group-bordered">
            <ReactAvatar text="SM" size="sm" />
            <ReactAvatar text="SM" size="sm" />
            <ReactAvatar text="SM" size="sm" />
          </ReactAvatarGroup>
        </div>
        <div className="stacked-mobile mbe3">
          <ReactAvatarGroup className="avatar-group-bordered">
            <ReactAvatar text="MD" size="md" />
            <ReactAvatar text="MD" size="md" />
            <ReactAvatar text="MD" size="md" />
          </ReactAvatarGroup>
        </div>
        <div className="stacked-mobile">
          <ReactAvatarGroup className="avatar-group-bordered">
            <ReactAvatar text="XL" size="xl" />
            <ReactAvatar text="XL" size="xl" />
            <ReactAvatar text="XL" size="xl" />
          </ReactAvatarGroup>
        </div>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">With Variants</h2>
        <ReactAvatarGroup className="avatar-group-bordered">
          <ReactAvatar text="DF" variant="default" size="lg" />
          <ReactAvatar text="IN" variant="info" size="lg" />
          <ReactAvatar text="WN" variant="warning" size="lg" />
          <ReactAvatar text="SC" variant="success" size="lg" />
          <ReactAvatar text="ER" variant="error" size="lg" />
          <ReactAvatar text="MC" variant="monochrome" size="lg" />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2>Avatar Group Custom Styling</h2>
        <p className="mbs2 mbe3">
          Use CSS Shadow Parts to customize avatar group layouts and effects.
        </p>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Custom Spacing (No Overlap)</h2>
        <ReactAvatarGroup className="custom-avatar-group">
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=20"
            imgAlt="User 1"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=21"
            imgAlt="User 2"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=22"
            imgAlt="User 3"
            size="lg"
          />
          <ReactAvatar
            imgSrc="https://i.pravatar.cc/150?img=23"
            imgAlt="User 4"
            size="lg"
          />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2 className="mbe2">Enhanced Hover Effects</h2>
        <ReactAvatarGroup className="stacked-group">
          <ReactAvatar text="AB" variant="info" size="lg" />
          <ReactAvatar text="CD" variant="success" size="lg" />
          <ReactAvatar text="EF" variant="warning" size="lg" />
          <ReactAvatar text="GH" variant="error" size="lg" />
        </ReactAvatarGroup>
      </div>

      <div className="mbe4">
        <h2>CSS Shadow Parts Customization</h2>
        <p className="mbs2 mbe3">
          Use CSS Shadow Parts to customize the avatar's appearance without
          affecting the component's internal styling. The following are meant
          solely to show how to utilize CSS shadow parts to create custom avatar
          styles. They are NOT meant to represent best practices or good taste in
          avatar design!
        </p>
      </div>
      <div className="stacked-mobile mbe4">
        <ReactAvatar className="custom-avatar-gradient" text="GR" />
        <ReactAvatar
          className="custom-avatar-border"
          imgSrc="https://i.pravatar.cc/150?img=8"
          imgAlt="Custom border"
        />
      </div>

      {/* CSS Shadow Parts customization styles */}
      <style>{`
        /* Avatar Group base styling */
        .avatar-group-bordered ag-avatar::part(ag-avatar) {
          border: 2px solid white;
        }

        /* CSS Shadow Parts customization examples */
        .custom-avatar-gradient::part(ag-avatar) {
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          color: white;
          border: 3px solid #fff;
          box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);
          font-weight: 700;
        }

        .custom-avatar-border::part(ag-avatar) {
          border: 4px solid #10b981;
          box-shadow: 0 0 0 4px rgba(16, 185, 129, 0.2);
        }

        /* Avatar Group custom styling examples */
        .custom-avatar-group::part(ag-avatar-group) {
          gap: 0.5rem;
        }

        .custom-avatar-group ag-avatar::part(ag-avatar) {
          border: 3px solid #fff;
          box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
        }

        .custom-avatar-group ag-avatar:not(:first-child) {
          margin-inline-start: 0;
        }

        .stacked-group ag-avatar::part(ag-avatar) {
          border: 3px solid #10b981;
        }

        .stacked-group ag-avatar {
          transition: all 0.3s ease;
        }

        .stacked-group ag-avatar:hover {
          transform: translateY(-8px) scale(1.1);
          z-index: 100 !important;
        }
      `}</style>
    </section>
  );
}

Open in StackBlitz

Usage

TIP

The framework examples below import AgnosticUI as an npm package. Alternatively, you can use the CLI for complete control, AI/LLM visibility, and full code ownership:

bash

npx ag init --framework FRAMEWORK # react, vue, lit, svelte, etc.
npx ag add Avatar

The CLI copies source code directly into your project, giving you full visibility and control. After running npx ag add, you'll receive exact import instructions.

Vue

vue

<template>
  <div>
    <VueAvatar text="AB" />

    <VueAvatar
      img-src="https://testingbot.com/free-online-tools/random-avatar/100"
      img-alt="User name"
    />

    <VueAvatar size="lg" variant="info">
      <UserIcon />
    </VueAvatar>

    <VueAvatarGroup>
      <VueAvatar text="AB" variant="info" size="lg" />
      <VueAvatar text="CD" variant="info" size="lg" />
      <VueAvatar text="EF" variant="info" size="lg" />
      <VueAvatar text="GH" variant="info" size="lg" />
    </VueAvatarGroup>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { VueAvatar, VueAvatarGroup } from 'agnosticui-core/avatar/vue';

export default defineComponent({
  components: { VueAvatar, VueAvatarGroup }
});
</script>

React

tsx

import { ReactAvatar, ReactAvatarGroup } from "agnosticui-core/avatar/react";

export default function Example() {
  return (
    <div>
      <ReactAvatar text="AB" />

      <ReactAvatar
        imgSrc="https://testingbot.com/free-online-tools/random-avatar/100"
        imgAlt="User name"
      />

      <ReactAvatar size="lg" variant="info">
        <UserIcon />
      </ReactAvatar>

      <ReactAvatarGroup>
        <ReactAvatar text="AB" variant="info" size="lg" />
        <ReactAvatar text="CD" variant="info" size="lg" />
        <ReactAvatar text="EF" variant="info" size="lg" />
        <ReactAvatar text="GH" variant="info" size="lg" />
      </ReactAvatarGroup>
    </div>
  );
}

Lit (Web Components)

html

<script type="module">
  import "agnosticui-core/avatar";
</script>

<ag-avatar text="AB"></ag-avatar>

<ag-avatar
  img-src="https://testingbot.com/free-online-tools/random-avatar/100"
  img-alt="User name"
></ag-avatar>

<ag-avatar size="lg" variant="info">
  <svg>...</svg>
</ag-avatar>

<ag-avatar-group>
  <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="CD" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="EF" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="GH" variant="info" size="lg"></ag-avatar>
</ag-avatar-group>

Props

Avatar

Prop	Type	Default	Description
`text`	`string`	`''`	Text content to display (typically initials like "AB")
`imgSrc`	`string`	`''`	Image source URL
`imgAlt`	`string`	`''`	Alt text for the image (required when imgSrc is provided for accessibility)
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size of the avatar
`shape`	`'circle' \| 'square' \| 'rounded'`	`'circle'`	Shape of the avatar
`variant`	`'default' \| 'info' \| 'warning' \| 'success' \| 'error' \| 'transparent'`	`'default'`	Color variant
`ariaLabel`	`string`	`''`	ARIA label for accessibility (auto-generated from text/imgAlt if not provided)

Avatar Group

The Avatar Group component wraps multiple Avatar components and automatically handles their layout and overlap styling.

Events

The Avatar component does not emit any events. It is a presentational component.

CSS Shadow Parts

Avatar

Part	Description
`ag-avatar`	The main avatar container element
`ag-avatar-image`	The image element (when imgSrc is provided)
`ag-avatar-text`	The text/initials container (when text is provided)

Avatar Group

Part	Description
`ag-avatar-group`	The main avatar group container element

Customization Example

css

.custom-avatar::part(ag-avatar) {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border: 3px solid #fff;
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.3);
  font-weight: 700;
}

.custom-avatar-image::part(ag-avatar) {
  border: 4px solid #10b981;
  box-shadow: 0 0 0 4px rgba(16, 185, 129, 0.2);
}

.custom-avatar-text::part(ag-avatar-text) {
  font-family: "Courier New", monospace;
  letter-spacing: 2px;
}

ag-avatar-group ag-avatar::part(ag-avatar) {
  border: 2px solid white;
}

.custom-avatar-group::part(ag-avatar-group) {
  gap: 0.5rem;
}

.custom-avatar-group ag-avatar::part(ag-avatar) {
  border: 3px solid #fff;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

.custom-avatar-group ag-avatar:not(:first-child) {
  margin-inline-start: 0;
}

.stacked-group ag-avatar::part(ag-avatar) {
  border: 3px solid #10b981;
}

.stacked-group ag-avatar {
  transition: all 0.3s ease;
}

.stacked-group ag-avatar:hover {
  transform: translateY(-8px) scale(1.1);
  z-index: 100 !important;
}

html

<VueAvatar class="custom-avatar" text="AB" />
<VueAvatar class="custom-avatar-image" img-src="..." img-alt="User" />

<VueAvatarGroup class="custom-avatar-group">
  <VueAvatar img-src="..." img-alt="User 1" size="lg" />
  <VueAvatar img-src="..." img-alt="User 2" size="lg" />
</VueAvatarGroup>

<ReactAvatar className="custom-avatar" text="AB" />
<ReactAvatar className="custom-avatar-image" imgSrc="..." imgAlt="User" />

<ReactAvatarGroup className="custom-avatar-group">
  <ReactAvatar imgSrc="..." imgAlt="User 1" size="lg" />
  <ReactAvatar imgSrc="..." imgAlt="User 2" size="lg" />
</ReactAvatarGroup>

<ag-avatar class="custom-avatar" text="AB"></ag-avatar>
<ag-avatar class="custom-avatar-image" img-src="..." img-alt="User"></ag-avatar>

<ag-avatar-group class="custom-avatar-group">
  <ag-avatar img-src="..." img-alt="User 1" size="lg"></ag-avatar>
  <ag-avatar img-src="..." img-alt="User 2" size="lg"></ag-avatar>
</ag-avatar-group>

Accessibility

The Avatar component is designed to be accessible by default:

Role: Uses role="img" when content is meaningful, or role="presentation" for decorative images without alt text
ARIA Label: Automatically sets appropriate aria-label from:
1. ariaLabel prop if provided
2. imgAlt if using an image
3. text if using initials
4. Falls back to "Avatar" if none provided
Images: Always provide imgAlt for images that convey user identity
Decorative: Omit imgAlt for purely decorative images (e.g., placeholder avatars)

Best Practices

Meaningful Images: Always include descriptive imgAlt text for user profile images
Initials: When using text for initials, ensure they represent the user's actual name
Icons: For icon-only avatars, provide an appropriate ariaLabel describing what the icon represents
Decorative: If the avatar is purely decorative and adjacent text provides context, you can omit alt text

Examples

html

<!-- Good: Meaningful image with alt text -->
<ag-avatar img-src="user.jpg" img-alt="Jane Doe"></ag-avatar>

<!-- Good: Initials with custom aria-label -->
<ag-avatar text="JD" aria-label="Jane Doe"></ag-avatar>

<!-- Good: Icon with descriptive label -->
<ag-avatar aria-label="Administrator account">
  <UserIcon />
</ag-avatar>

<!-- Acceptable: Decorative avatar (adjacent to name) -->
<div>
  <ag-avatar img-src="user.jpg"></ag-avatar>
  <span>Jane Doe</span>
</div>

Common Patterns

Avatar Group

Display multiple avatars together (e.g., for collaborators, team members, or participants):

html

<ag-avatar-group>
  <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="CD" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="EF" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="GH" variant="info" size="lg"></ag-avatar>
</ag-avatar-group>

<ag-avatar-group>
  <ag-avatar img-src="user1.jpg" img-alt="User 1" size="lg"></ag-avatar>
  <ag-avatar img-src="user2.jpg" img-alt="User 2" size="lg"></ag-avatar>
  <ag-avatar img-src="user3.jpg" img-alt="User 3" size="lg"></ag-avatar>
</ag-avatar-group>

<ag-avatar-group>
  <ag-avatar text="AB" variant="info" size="lg"></ag-avatar>
  <ag-avatar text="RL" variant="info" size="lg"></ag-avatar>
  <ag-avatar size="lg">
    <UserIcon />
  </ag-avatar>
  <ag-avatar img-src="user1.jpg" img-alt="User 1" size="lg"></ag-avatar>
</ag-avatar-group>

Avatar Group with Count Indicator

Show remaining count when there are many users:

html

<ag-avatar-group>
  <ag-avatar img-src="user1.jpg" img-alt="User 1" size="sm"></ag-avatar>
  <ag-avatar img-src="user2.jpg" img-alt="User 2" size="sm"></ag-avatar>
  <ag-avatar text="+5" size="sm" variant="info" aria-label="5 more users"></ag-avatar>
</ag-avatar-group>

Status Indicator

Combine with custom CSS for status indicators:

css

.avatar-online::part(ag-avatar)::after {
  content: '';
  position: absolute;
  bottom: 0;
  right: 0;
  width: 12px;
  height: 12px;
  background: #10b981;
  border: 2px solid white;
  border-radius: 50%;
}

Fallback Pattern

Handle missing images gracefully:

vue

<template>
  <VueAvatar
    :img-src="user.avatar || ''"
    :text="user.avatar ? '' : user.initials"
    :img-alt="user.name"
  />
</template>

Avatar ​

Examples ​

Text Initials

With Images

Sizes

Shapes

Variants

With Icons

Avatar Groups

Text Avatars

Image Avatars

Mixed Content

Different Sizes

With Variants

Avatar Group Custom Styling

Custom Spacing (No Overlap)

Enhanced Hover Effects

CSS Shadow Parts Customization

Usage ​

Props ​

Avatar ​

Avatar Group ​

Events ​

CSS Shadow Parts ​

Avatar ​

Avatar Group ​

Customization Example ​

Accessibility ​

Best Practices ​

Examples ​

Common Patterns ​

Avatar Group ​

Avatar Group with Count Indicator ​

Status Indicator ​

Fallback Pattern ​

Avatar

Examples

Usage

Props

Avatar

Avatar Group

Events

CSS Shadow Parts

Avatar

Avatar Group

Customization Example

Accessibility

Best Practices

Examples

Common Patterns

Avatar Group

Avatar Group with Count Indicator

Status Indicator

Fallback Pattern