basecoat/site/src/docs/components/avatar.mdx

# Avatar

<Preview>
<div class="flex flex-row flex-wrap items-center gap-12">
  <span class="avatar">
    <img src="https://github.com/shadcn.png" alt="@shadcn" />
    <span>CN</span>
  </span>
  <span class="avatar rounded-lg">
    <img src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
    <span>ER</span>
  </span>
  <div class="avatar-group [&_.avatar]:grayscale">
    <span class="avatar">
      <img src="https://github.com/shadcn.png" alt="@shadcn" />
      <span>CN</span>
    </span>
    <span class="avatar">
      <img src="https://github.com/maxleiter.png" alt="@maxleiter" />
      <span>LR</span>
    </span>
    <span class="avatar">
      <img src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
      <span>ER</span>
    </span>
  </div>
</div>
</Preview>

## Usage

<Steps>
  <Step title="Include CSS">

Import Tailwind and one full Basecoat style bundle.

```css
@import "tailwindcss";
@import "basecoat-css/vega.css";
```

Or import only the base CSS, Avatar component CSS, and one style pack.

```css
@import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/avatar.css";
@import "basecoat-css/styles/vega.css";
```

Using CDN or bundler imports? See the [Installation page](/installation).

  </Step>
  <Step title="Add your avatar HTML">

Add `class="avatar"` to a small inline container. Add `data-size="sm"` or `data-size="lg"` when needed. Put the image first and a fallback `<span>` after it. Add `.avatar-badge` for a status badge or badge icon.

```html
<span class="avatar">
  <img src="https://github.com/shadcn.png" alt="@shadcn" />
  <span>CN</span>
</span>
```

  </Step>
</Steps>

### HTML structure

<dl>
  <dt><code>&lt;div class="avatar-group"&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
  <dd>
    Optional parent that groups avatars with overlap.
    <dl>
      <dt><code>&lt;span class="avatar"&gt;</code></dt>
      <dd>
        Avatar root. Use it standalone or as a direct child of <code>.avatar-group</code>. Add <code>data-size="sm"</code> or <code>data-size="lg"</code> for alternate sizes.
        <dl>
          <dt><code>&lt;img&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>The avatar image. Provide meaningful <code>alt</code> text.</dd>
          <dt><code>&lt;span&gt;</code></dt>
          <dd>Fallback initials or icon.</dd>
          <dt><code>&lt;span class="avatar-badge"&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
          <dd>Status badge positioned at the block-end inline-end corner. It can be empty or contain an icon.</dd>
        </dl>
      </dd>
      <dt><code>&lt;span data-count&gt;</code> <span class="badge" data-variant="secondary">Optional</span></dt>
      <dd>Count or icon indicator displayed at the end of the group.</dd>
    </dl>
  </dd>
</dl>

## Examples

### Basic

<Preview>
<span class="avatar">
  <img src="https://github.com/shadcn.png" alt="@shadcn" />
  <span>CN</span>
</span>
</Preview>

### Badge

<Preview>
<span class="avatar">
  <img src="https://github.com/shadcn.png" alt="@shadcn" />
  <span>CN</span>
  <span class="avatar-badge bg-green-600 dark:bg-green-800"></span>
</span>
</Preview>

### Badge with icon

<Preview>
<span class="avatar">
  <img src="https://github.com/pranathip.png" alt="@pranathip" />
  <span>PP</span>
  <span class="avatar-badge"><svg class="lucide lucide-plus" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14" /><path d="M12 5v14" /></svg></span>
</span>
</Preview>

### Avatar group

<Preview>
<div class="avatar-group">
  <span class="avatar"><img src="https://github.com/shadcn.png" alt="@shadcn" /><span>CN</span></span>
  <span class="avatar"><img src="https://github.com/maxleiter.png" alt="@maxleiter" /><span>LR</span></span>
  <span class="avatar"><img src="https://github.com/evilrabbit.png" alt="@evilrabbit" /><span>ER</span></span>
</div>
</Preview>

### Avatar group count

<Preview>
<div class="avatar-group">
  <span class="avatar"><img src="https://github.com/shadcn.png" alt="@shadcn" /><span>CN</span></span>
  <span class="avatar"><img src="https://github.com/maxleiter.png" alt="@maxleiter" /><span>LR</span></span>
  <span class="avatar"><img src="https://github.com/evilrabbit.png" alt="@evilrabbit" /><span>ER</span></span>
  <span data-count>+3</span>
</div>
</Preview>

### Avatar group with icon

<Preview>
<div class="avatar-group">
  <span class="avatar"><img src="https://github.com/shadcn.png" alt="@shadcn" /><span>CN</span></span>
  <span class="avatar"><img src="https://github.com/maxleiter.png" alt="@maxleiter" /><span>LR</span></span>
  <span class="avatar"><img src="https://github.com/evilrabbit.png" alt="@evilrabbit" /><span>ER</span></span>
  <span data-count aria-label="Additional avatars"><svg class="lucide lucide-plus" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14" /><path d="M12 5v14" /></svg></span>
</div>
</Preview>

### Sizes

<Preview>
<div class="grid gap-2">
  <div class="flex flex-wrap items-center gap-2">
    <span class="avatar" data-size="sm">
      <img src="https://github.com/shadcn.png" alt="@shadcn" />
      <span>CN</span>
    </span>
    <span class="avatar">
      <img src="https://github.com/shadcn.png" alt="@shadcn" />
      <span>CN</span>
    </span>
    <span class="avatar" data-size="lg">
      <img src="https://github.com/shadcn.png" alt="@shadcn" />
      <span>CN</span>
    </span>
  </div>
  <div class="flex flex-wrap items-center gap-2">
    <span class="avatar" data-size="sm"><span>CN</span></span>
    <span class="avatar"><span>CN</span></span>
    <span class="avatar" data-size="lg"><span>CN</span></span>
  </div>
</div>
</Preview>

### Dropdown

<Preview>
<div class="dropdown-menu">
  <button type="button" id="avatar-dropdown-trigger" aria-label="Open user menu" aria-haspopup="menu" aria-controls="avatar-dropdown-menu" aria-expanded="false" class="btn rounded-full" data-variant="ghost" data-size="icon">
    <span class="avatar">
      <img src="https://github.com/shadcn.png" alt="@shadcn" />
      <span>CN</span>
    </span>
  </button>
  <div data-popover aria-hidden="true" class="w-32">
    <div role="menu" id="avatar-dropdown-menu" aria-labelledby="avatar-dropdown-trigger">
      <div role="menuitem">Profile</div>
      <div role="menuitem">Billing</div>
      <div role="menuitem">Settings</div>
      <hr role="separator" />
      <div role="menuitem" data-variant="destructive">Log out</div>
    </div>
  </div>
</div>
</Preview>

### RTL

<Preview>
<div class="flex flex-row flex-wrap items-center gap-12" dir="rtl">
  <span class="avatar">
    <img src="https://github.com/shadcn.png" alt="@shadcn" />
    <span>CN</span>
  </span>
  <span class="avatar rounded-lg">
    <img src="https://github.com/evilrabbit.png" alt="@evilrabbit" />
    <span>ER</span>
  </span>
  <div class="avatar-group [&_.avatar]:grayscale">
    <span class="avatar"><img src="https://github.com/shadcn.png" alt="@shadcn" /><span>CN</span></span>
    <span class="avatar"><img src="https://github.com/maxleiter.png" alt="@maxleiter" /><span>LR</span></span>
    <span class="avatar"><img src="https://github.com/evilrabbit.png" alt="@evilrabbit" /><span>ER</span></span>
  </div>
</div>
</Preview>