v0.1.0

Appearance

Avatar <l-avatar> ​

Avatars are used to represent a user or entity with a profile image, initials, or icon fallback. Commonly used in headers, comments, contact lists, and user cards.

HTML tag<l-avatar>
⏣Native HTML
⬡Progressive
◇Custom
⬢Shadow DOM
Custom Element · Shadow DOM

Options ​

Image ​

Set src and name attributes. Falls back to initials if the image fails to load.

Code
html
<l-avatar
  src="https://i.pravatar.cc/150?img=58"
  name="John Doe"
></l-avatar>
<l-avatar
  src="https://i.pravatar.cc/150?img=32"
  name="Jane Smith"
></l-avatar>
<l-avatar
  src="https://i.pravatar.cc/150?img=11"
  name="Alex Chen"
></l-avatar>

Initials ​

Set name to auto-extract initials, or slot custom text content.

+5
Code
html
<l-avatar name="John Doe"></l-avatar>
<l-avatar name="Jane Smith"></l-avatar>
<l-avatar name="Alex"></l-avatar>
<l-avatar>+5</l-avatar>

Custom colors ​

Set --color to a base color. Text is auto-derived via relative color syntax.

Code
html
<div class="flex items-end gap-3">
  <l-avatar
    style="--color: var(--color-red-200)"
    name="Anna Bell"
  ></l-avatar>
  <l-avatar
    style="--color: var(--color-orange-200)"
    name="Bob Chen"
  ></l-avatar>
  <l-avatar
    style="--color: var(--color-yellow-200)"
    name="Cleo Dane"
  ></l-avatar>
  <l-avatar
    style="--color: var(--color-green-200)"
    name="Dan Evans"
  ></l-avatar>
  <l-avatar
    style="--color: var(--color-blue-200)"
    name="Eve Fox"
  ></l-avatar>
  <l-avatar
    style="--color: var(--color-purple-200)"
    name="Fay Grant"
  ></l-avatar>
</div>

Sizes ​

Add the size attribute: xs, sm, md (default), lg, or xl.

Code
html
<div class="flex items-end gap-3">
  <l-avatar
    size="xs"
    name="John Doe"
  ></l-avatar>
  <l-avatar
    size="sm"
    name="John Doe"
  ></l-avatar>
  <l-avatar name="John Doe"></l-avatar>
  <l-avatar
    size="lg"
    name="John Doe"
  ></l-avatar>
  <l-avatar
    size="xl"
    name="John Doe"
  ></l-avatar>
</div>

Circle ​

Set --appearance: circle for a fully circular shape. Default is a rounded square.

Code
html
<l-avatar
  style="--appearance: circle"
  src="https://i.pravatar.cc/150?img=58"
  name="John Doe"
></l-avatar>
<l-avatar
  style="--appearance: circle"
  name="Jane Smith"
></l-avatar>
<l-avatar style="--appearance: circle"></l-avatar>

Badge ​

Set badge to a number to show a count indicator at the bottom-right corner.

Code
html
<l-avatar
  badge="3"
  src="https://i.pravatar.cc/150?img=58"
  name="John Doe"
></l-avatar>
<l-avatar
  badge="25"
  src="https://i.pravatar.cc/150?img=32"
  name="Jane Smith"
></l-avatar>
<l-avatar
  badge="99"
  name="Alex Chen"
></l-avatar>

Interactive ​

Add the interactive attribute to render the avatar as a <button>. Includes focus ring and hover state.

Code
html
<l-avatar
  interactive
  src="https://i.pravatar.cc/150?img=58"
  name="John Doe"
></l-avatar>
<l-avatar
  interactive
  name="Jane Smith"
></l-avatar>
<l-avatar
  interactive
  style="--appearance: circle"
  src="https://i.pravatar.cc/150?img=32"
  name="Alex Chen"
></l-avatar>

Group ​

Wrap avatars in .l-avatar-group for an overlapping stack with a surface-colored ring.

Code
html
<div class="grid gap-4">
  <div class="l-avatar-group">
    <l-avatar
      src="https://i.pravatar.cc/150?img=58"
      name="John Doe"
    ></l-avatar>
    <l-avatar
      src="https://i.pravatar.cc/150?img=32"
      name="Jane Smith"
    ></l-avatar>
    <l-avatar
      src="https://i.pravatar.cc/150?img=12"
      name="Alex Chen"
    ></l-avatar>
    <l-avatar name="Sam Wilson"></l-avatar>
  </div>
  <div class="l-avatar-group">
    <l-avatar
      style="--appearance: circle"
      src="https://i.pravatar.cc/150?img=58"
      name="John Doe"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle"
      src="https://i.pravatar.cc/150?img=32"
      name="Jane Smith"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle"
      src="https://i.pravatar.cc/150?img=12"
      name="Alex Chen"
    ></l-avatar>
    <l-avatar
      style="--appearance: circle"
      name="Sam Wilson"
    ></l-avatar>
  </div>
</div>

Accessibility ​

Criteria ​

Role

Default role="img" communicates the avatar as an image

WCAG4.1.2
RGAA1.1
Accessible name

aria-label is set automatically from the name attribute

WCAG1.1.14.1.2
RGAA1.1
Interactive mode

When interactive is set, renders as a <button> with focus ring and hover states

WCAG2.4.7
RGAA10.7
Decorative elements

Badge count is hidden from assistive tech with aria-hidden="true"

WCAG1.1.1
Image fallback

Falls back to initials (then default icon) if image fails to load

WCAG1.1.1

Keyboard interactions ​

When interactive is set:

Enter
Activates the avatar button
Space
Activates the avatar button
Tab
Moves focus to the next focusable element

API reference ​

Importing ​

js
import 'luxen-ui/avatar';

Attributes & Properties ​

srcAttribute
Image URL for the avatar
nameAttribute
Full name used for initials extraction and aria-label
sizeAttribute
Avatar size: xs (24px), sm (32px), md (40px, default), lg (48px), xl (56px)
badgeAttribute
Number. Shows a count indicator at bottom-right
interactiveAttribute
Boolean. Renders as a <button> with focus and hover states

CSS classes ​

.l-avatar-groupClass
Flex container with negative margins and surface-colored ring for overlapping avatars

CSS custom properties ​

--colorProperty
Base color for initials/icon background. Text color is auto-derived via relative color syntax
--appearanceProperty
Set to circle for a fully circular shape (default is rounded square)