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
Copy and paste the following code into your project.
/**
* 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
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.
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.
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.
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.
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.
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.
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().
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
Dropdown
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.
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.
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.
avatarFallbackClass
avatarFallbackClass() styles the fallback, shown when the image is missing or fails to load. Always include it so the avatar is still named.
avatarBadgeClass
avatarBadgeClass() styles a badge indicator on the avatar, positioned at the bottom right (the inline end under dir="rtl").
avatarGroupClass
avatarGroupClass() displays a group of avatars with overlapping styling.
avatarGroupCountClass
avatarGroupCountClass() displays a count indicator in an avatar group, typically showing the number of additional avatars.