v0.21.4

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
⬡Progressive
◇Plain
⬢Shadow-DOM
Shadow-DOM Custom Element

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. The text color is auto-derived from its luminance, staying readable on both pastel and saturated backgrounds.

Code
html
<div class="flex items-end gap-3">
  <l-avatar
    style="--color: #dc2626"
    name="Anna Bell"
  ></l-avatar>
  <l-avatar
    style="--color: #2f489a"
    name="Bob Chen"
  ></l-avatar>
  <l-avatar
    style="--color: #00a63e"
    name="Cleo Dane"
  ></l-avatar>
  <l-avatar
    style="--color: #ffc9c9"
    name="Dan Evans"
  ></l-avatar>
  <l-avatar
    style="--color: #bedbff"
    name="Eve Fox"
  ></l-avatar>
  <l-avatar
    style="--color: #e9d4ff"
    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>

Custom size ​

Set --size to any length for an arbitrary pixel size. It overrides the size scale and the font follows proportionally. Use it alone — not combined with a size token.

Code
html
<div class="flex items-end gap-3">
  <l-avatar
    style="--size: 20px"
    name="John Doe"
  ></l-avatar>
  <l-avatar
    style="--size: 44px; --appearance: circle"
    src="https://i.pravatar.cc/150?img=58"
    name="John Doe"
  ></l-avatar>
  <l-avatar
    style="--size: 64px; --color: #2f489a"
    name="Jane Smith"
  ></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

Rules

  • Always provide the name attribute — it drives both aria-label and the initials fallback
  • Add interactive only when the avatar triggers an action (e.g., opens a profile menu)

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 ​

srcstringProperty
Image URL. Falls back to initials (then the default icon) if it fails to load.
namestringProperty
Name used as the accessible label and to derive the initials fallback.
sizestringdefault:'md'Property
Avatar size: xs, sm, md (default), lg, or xl.
badgenumberdefault:0Property
Count shown in the corner badge. 0 hides the badge.
interactivebooleandefault:falseProperty
Render as a <button> with focus ring and hover states.

CSS classes ​

.l-avatar-groupClass
Flex wrapper that overlaps a row of stacked avatars.

CSS custom properties ​

--sizedefault:40pxCustom property
Box size (any length). Set it inline (e.g. style="--size: 20px") for an arbitrary size beyond the size token scale; the font then follows proportionally. The size attribute sets it to the matching token.
--colorCustom property
Background fill color for initials and the default icon.
--text-colorCustom property
Initials/icon color over --color. Defaults to an auto-derived readable color; set it to enforce a specific brand color (overrides the automatic choice).
--appearanceCustom property
Set to circle for a fully circular avatar (default is a rounded square).

CSS parts ​

basePart
The avatar container that paints --color; style it (e.g. color) to override the auto-derived text color.