# Avatar

An image element with a fallback for representing the user.

Source: https://webjs.dev/ui/docs/components/avatar

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarBadgeClass,
  avatarGroupClass, avatarGroupCountClass,
} from '#components/ui/avatar.ts';

export default function AvatarDemo() {
  return html`
    <div class="flex flex-row flex-wrap items-center gap-6 md:gap-12">
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${cn(avatarImageClass(), 'grayscale')}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
        <span data-slot="avatar-badge" class=${cn(avatarBadgeClass(), 'bg-green-600 dark:bg-green-800')}></span>
      </span>
      <div data-slot="avatar-group" class=${cn(avatarGroupClass(), 'grayscale')}>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
        </span>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
        </span>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
        </span>
        <div data-slot="avatar-group-count" class=${avatarGroupCountClass()}>+3</div>
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add avatar
```

### Copy and paste the following code into your project.

````ts title="components/ui/avatar.ts"
/**
 * Avatar: circular user image with fallback. Tier-1 class helpers;
 * compose with a native `<span>` or `<img>`. As in shadcn, one of the two
 * shows, never both, and with no script: the image is laid over the fallback
 * (`absolute inset-0` inside the `relative` root), so a loaded image covers
 * it, and a missing or broken one leaves the fallback showing. A broken
 * image paints neither its alt text (`text-transparent`) nor, in Chromium,
 * its broken-image glyph: a broken `<img>` renders a `::before` box (a loaded
 * one never does), and the full-height block it gets here pushes the glyph
 * out of the clipped box. Safari ignores that box and draws its glyph over
 * the initials (Firefox can too at larger sizes), so where that matters hide
 * the image on failure with script (`onerror`).
 *
 * shadcn parity:
 *   Avatar (size: default | sm | lg)  → avatarClass({ size }) with `data-size`
 *   AvatarImage                       → avatarImageClass()
 *   AvatarFallback                    → avatarFallbackClass()
 *   AvatarBadge                       → avatarBadgeClass()
 *   AvatarGroup                       → avatarGroupClass()
 *   AvatarGroupCount                  → avatarGroupCountClass()
 *
 * A11y (required for accessible output): the <img> MUST have an alt that
 * names the person (alt="Vivek Khandelwal"), or alt="" when a visible text
 * fallback already names them. Always provide the fallback <span> so the
 * avatar is still named if the image fails to load.
 *
 * Design tokens used: --muted, --muted-foreground, --primary, --background.
 *
 * @example
 * ```html
 * <span class=${avatarClass()} data-size="default" data-slot="avatar">
 *   <img class=${avatarImageClass()} src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
 *   <span class=${avatarFallbackClass()}>VK</span>
 * </span>
 *
 * <div class=${avatarGroupClass()}>
 *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
 *     <img class=${avatarImageClass()} src="/avatars/vivek.jpg" alt="Vivek Khandelwal">
 *     <span class=${avatarFallbackClass()}>VK</span>
 *   </span>
 *   <span class=${avatarClass()} data-size="default" data-slot="avatar">
 *     <img class=${avatarImageClass()} src="/avatars/amir.jpg" alt="Amir Rao">
 *     <span class=${avatarFallbackClass()}>AR</span>
 *   </span>
 *   <div class=${avatarGroupCountClass()}>+3</div>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

export type AvatarSize = 'default' | 'sm' | 'lg';

const AVATAR_BASE =
  'size-8 overflow-hidden rounded-full data-[size=lg]:size-10 data-[size=sm]:size-6 group/avatar relative flex shrink-0 select-none';

export function avatarClass(_opts: { size?: AvatarSize } = {}): string {
  // Size driven by data-size attribute on the element (matches shadcn).
  return cn(AVATAR_BASE);
}

export const avatarImageClass = (): string =>
  'absolute inset-0 aspect-square size-full object-cover overflow-hidden text-transparent before:block before:h-full';

export const avatarFallbackClass = (): string =>
  'rounded-full bg-muted text-muted-foreground flex size-full items-center justify-center text-sm group-data-[size=sm]/avatar:text-xs';

export const avatarBadgeClass = (): string =>
  'bg-primary text-primary-foreground ring-background group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2 group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2 absolute end-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-blend-color ring-2 select-none';

export const avatarGroupClass = (): string =>
  'group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background';

export const avatarGroupCountClass = (): string =>
  'size-8 rounded-full bg-muted text-sm text-muted-foreground group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3 relative flex shrink-0 items-center justify-center ring-2 ring-background';
````

### Update the import paths to match your project setup.

## Usage

```ts
import {
  avatarClass,
  avatarImageClass,
  avatarFallbackClass,
} from '#components/ui/avatar.ts';
```

```ts
<span data-slot="avatar" data-size="default" class=${avatarClass()}>
  <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
  <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
</span>
```

## Composition

Use the following composition to build an avatar:

```text
avatarClass()
├── avatarImageClass()
├── avatarFallbackClass()
└── avatarBadgeClass()
```

Use the following composition to build an avatar group:

```text
avatarGroupClass()
├── avatarClass()
│   ├── avatarImageClass()
│   ├── avatarFallbackClass()
│   └── avatarBadgeClass()
├── avatarClass()
│   ├── avatarImageClass()
│   ├── avatarFallbackClass()
│   └── avatarBadgeClass()
└── avatarGroupCountClass()
```

## Basic

A basic avatar with an image and a fallback.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { avatarClass, avatarImageClass, avatarFallbackClass } from '#components/ui/avatar.ts';

export default function AvatarDemo() {
  return html`
    <span data-slot="avatar" data-size="default" class=${avatarClass()}>
      <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${cn(avatarImageClass(), 'grayscale')}>
      <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
    </span>
  `;
}
```

## Badge

Use `avatarBadgeClass()` to add a badge to the avatar. The badge is positioned at the bottom right of the avatar.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarBadgeClass,
} from '#components/ui/avatar.ts';

export default function AvatarWithBadge() {
  return html`
    <span data-slot="avatar" data-size="default" class=${avatarClass()}>
      <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
      <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      <span data-slot="avatar-badge" class=${cn(avatarBadgeClass(), 'bg-green-600 dark:bg-green-800')}></span>
    </span>
  `;
}
```

Merge your own classes with the helper through `cn()` to add custom styles to the badge such as custom colors, sizes, etc.

```ts
<span data-slot="avatar" data-size="default" class=${avatarClass()}>
  <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
  <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
  <span data-slot="avatar-badge" class=${cn(avatarBadgeClass(), 'bg-green-600 dark:bg-green-800')}></span>
</span>
```

## Badge with Icon

You can also put an icon inside the badge.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarBadgeClass,
} from '#components/ui/avatar.ts';
import { PlusIcon } from '#lib/ui/lucide.ts';

export default function AvatarBadgeIconExample() {
  return html`
    <span data-slot="avatar" data-size="default" class=${cn(avatarClass(), 'grayscale')}>
      <img data-slot="avatar-image" src="https://github.com/pranathip.png" alt="@pranathip" class=${avatarImageClass()}>
      <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>PP</span>
      <span data-slot="avatar-badge" class=${avatarBadgeClass()}>
        ${PlusIcon()}
      </span>
    </span>
  `;
}
```

## Avatar Group

Use `avatarGroupClass()` to add a group of avatars.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarGroupClass,
} from '#components/ui/avatar.ts';

export default function AvatarGroupExample() {
  return html`
    <div data-slot="avatar-group" class=${cn(avatarGroupClass(), 'grayscale')}>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
      </span>
    </div>
  `;
}
```

## Avatar Group Count

Use `avatarGroupCountClass()` to add a count to the group.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarGroupClass, avatarGroupCountClass,
} from '#components/ui/avatar.ts';

export default function AvatarGroupCountExample() {
  return html`
    <div data-slot="avatar-group" class=${cn(avatarGroupClass(), 'grayscale')}>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
      </span>
      <div data-slot="avatar-group-count" class=${avatarGroupCountClass()}>+3</div>
    </div>
  `;
}
```

## Avatar Group with Icon

You can also put an icon inside the group count.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarGroupClass, avatarGroupCountClass,
} from '#components/ui/avatar.ts';
import { PlusIcon } from '#lib/ui/lucide.ts';

export default function AvatarGroupCountIconExample() {
  return html`
    <div data-slot="avatar-group" class=${cn(avatarGroupClass(), 'grayscale')}>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
      </span>
      <div data-slot="avatar-group-count" class=${avatarGroupCountClass()}>
        ${PlusIcon()}
      </div>
    </div>
  `;
}
```

## Sizes

Use the `data-size` attribute to change the size of the avatar. The styles key on it, so set it to match the `size` you pass to `avatarClass()`.

```ts
import { html } from '@webjsdev/core';
import { avatarClass, avatarImageClass, avatarFallbackClass } from '#components/ui/avatar.ts';

// The size rides the data-size attribute, which the styles key on.
export default function AvatarSizeExample() {
  return html`
    <div class="flex flex-wrap items-center gap-2 grayscale">
      <span data-slot="avatar" data-size="sm" class=${avatarClass({ size: 'sm' })}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="lg" class=${avatarClass({ size: 'lg' })}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
    </div>
  `;
}
```

## Dropdown

You can use an avatar inside the trigger of a `<ui-dropdown-menu>`.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { avatarClass, avatarImageClass, avatarFallbackClass } from '#components/ui/avatar.ts';

export default function AvatarDropdown() {
  return html`
    <ui-dropdown-menu>
      <ui-dropdown-menu-trigger>
        <button type="button" data-slot="button" data-variant="ghost" data-size="icon" class=${cn(buttonClass({ variant: 'ghost', size: 'icon' }), 'rounded-full')}>
          <span data-slot="avatar" data-size="default" class=${avatarClass()}>
            <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="vivek" class=${avatarImageClass()}>
            <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
          </span>
        </button>
      </ui-dropdown-menu-trigger>
      <ui-dropdown-menu-content class="w-32">
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item>Profile</ui-dropdown-menu-item>
          <ui-dropdown-menu-item>Billing</ui-dropdown-menu-item>
          <ui-dropdown-menu-item>Settings</ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
        <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
        <ui-dropdown-menu-group>
          <ui-dropdown-menu-item variant="destructive">Log out</ui-dropdown-menu-item>
        </ui-dropdown-menu-group>
      </ui-dropdown-menu-content>
    </ui-dropdown-menu>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  avatarClass, avatarImageClass, avatarFallbackClass, avatarBadgeClass,
  avatarGroupClass, avatarGroupCountClass,
} from '#components/ui/avatar.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      moreUsers: '+3',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      moreUsers: '+٣',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      moreUsers: '+3',
    },
  },
};

export default function AvatarRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div class="flex flex-row flex-wrap items-center gap-6 md:gap-12" dir=${dir} lang=${lang}>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${cn(avatarImageClass(), 'grayscale')}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
      </span>
      <span data-slot="avatar" data-size="default" class=${avatarClass()}>
        <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
        <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
        <span data-slot="avatar-badge" class=${cn(avatarBadgeClass(), 'bg-green-600 dark:bg-green-800')}></span>
      </span>
      <div data-slot="avatar-group" class=${cn(avatarGroupClass(), 'grayscale')}>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>VK</span>
        </span>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="https://github.com/maxleiter.png" alt="@maxleiter" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>LR</span>
        </span>
        <span data-slot="avatar" data-size="default" class=${avatarClass()}>
          <img data-slot="avatar-image" src="https://github.com/evilrabbit.png" alt="@evilrabbit" class=${avatarImageClass()}>
          <span data-slot="avatar-fallback" class=${avatarFallbackClass()}>ER</span>
        </span>
        <div data-slot="avatar-group-count" class=${avatarGroupCountClass()}>${t.moreUsers}</div>
      </div>
    </div>
  `;
}
```

## API Reference

Every part is a class helper you put on a native element, with the `data-slot` its styles key on.

### avatarClass

`avatarClass()` is the root that wraps the avatar image and fallback. Put it on a `<span>` and set `data-size`, which is what the styles read.

| Option / Attribute | Type | Default |
| --- | --- | --- |
| `size` / `data-size` | `"default" \| "sm" \| "lg"` | `"default"` |

### avatarImageClass

`avatarImageClass()` styles the avatar image. Put it on an `<img>` with a `src` and an `alt` that names the person, or `alt=""` when a visible text fallback already names them.

| Element | Attributes | Options |
| --- | --- | --- |
| `<img>` | `data-slot="avatar-image"` | none |

### avatarFallbackClass

`avatarFallbackClass()` styles the fallback, shown when the image is missing or fails to load. Always include it so the avatar is still named.

| Element | Attributes | Options |
| --- | --- | --- |
| `<span>` | `data-slot="avatar-fallback"` | none |

### avatarBadgeClass

`avatarBadgeClass()` styles a badge indicator on the avatar, positioned at the bottom right (the inline end under `dir="rtl"`).

| Element | Attributes | Options |
| --- | --- | --- |
| `<span>` | `data-slot="avatar-badge"` | none |

### avatarGroupClass

`avatarGroupClass()` displays a group of avatars with overlapping styling.

| Element | Attributes | Options |
| --- | --- | --- |
| `<div>` | `data-slot="avatar-group"` | none |

### avatarGroupCountClass

`avatarGroupCountClass()` displays a count indicator in an avatar group, typically showing the number of additional avatars.

| Element | Attributes | Options |
| --- | --- | --- |
| `<div>` | `data-slot="avatar-group-count"` | none |
