Skip to content
WebJs
Menu

An image element with a fallback for representing the user.

@vivek VK @evilrabbit ER
@vivek VK @maxleiter LR @evilrabbit ER
+3
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>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add avatar

Usage

import {
  avatarClass,
  avatarImageClass,
  avatarFallbackClass,
} from '#components/ui/avatar.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:

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

Use the following composition to build an avatar group:

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

Basic

A basic avatar with an image and a fallback.

@vivek VK
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>
  `;
}
View Code

Badge

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

@vivek VK
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>
  `;
}
View Code

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

<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.

@pranathip PP
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>
  `;
}
View Code

Avatar Group

Use avatarGroupClass() to add a group of avatars.

@vivek VK @maxleiter LR @evilrabbit ER
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>
  `;
}
View Code

Avatar Group Count

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

@vivek VK @maxleiter LR @evilrabbit ER
+3
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>
  `;
}
View Code

Avatar Group with Icon

You can also put an icon inside the group count.

@vivek VK @maxleiter LR @evilrabbit ER
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>
  `;
}
View Code

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().

@vivek VK @vivek VK @vivek VK
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>
  `;
}
View Code

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

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>
  `;
}
View Code

RTL

To enable RTL support, see the RTL configuration guide.

@vivek VK @evilrabbit ER
@vivek VK @maxleiter LR @evilrabbit ER
+٣
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>
  `;
}
View Code

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 / AttributeTypeDefault
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.

ElementAttributesOptions
<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.

ElementAttributesOptions
<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").

ElementAttributesOptions
<span>data-slot="avatar-badge"none

avatarGroupClass

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

ElementAttributesOptions
<div>data-slot="avatar-group"none

avatarGroupCountClass

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

ElementAttributesOptions
<div>data-slot="avatar-group-count"none