---
outline: deep
---

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

**`<l-avatar>`** — Custom Element · Shadow DOM

## Options

### Image

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

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

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

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

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

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

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

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

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

```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
- **Accessible name** — `aria-label` is set automatically from the `name` attribute
- **Interactive mode** — When `interactive` is set, renders as a `<button>` with focus ring and hover states
- **Decorative elements** — Badge count is hidden from assistive tech with `aria-hidden="true"`
- **Image fallback** — Falls back to initials (then default icon) if image fails to load

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

- **src**: `string` — Image URL. Falls back to initials (then the default icon) if it fails to load.
- **name**: `string` — Name used as the accessible label and to derive the initials fallback.
- **size**: `string` (default: `'md'`) — Avatar size: `xs`, `sm`, `md` (default), `lg`, or `xl`.
- **badge**: `number` (default: `0`) — Count shown in the corner badge. `0` hides the badge.
- **interactive**: `boolean` (default: `false`) — Render as a `<button>` with focus ring and hover states.

### CSS classes

- `.l-avatar-group` — Flex wrapper that overlaps a row of stacked avatars.

### CSS custom properties

- `--size` (default: `40px`) — 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.
- `--color` — Background fill color for initials and the default icon.
- `--text-color` — Initials/icon color over `--color`. Defaults to an auto-derived readable color; set it to enforce a specific brand color (overrides the automatic choice).
- `--appearance` — Set to `circle` for a fully circular avatar (default is a rounded square).

### CSS parts

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