Avatar

A square image slot with a text fallback underneath. The image paints over the fallback and hides itself when it has nothing to paint, revealing the initials. Class + data-attribute API mirrors the Badge: one .x-avatar class plus data-variant, data-size, data-accent.

InstallCopy Anchor Link

import "elements-kit/ui/styles.css";

import "elements-kit/ui/styles/palette/gray.css";
import "elements-kit/ui/styles/neutral/gray.css";
import "elements-kit/ui/styles/palette/iris.css";
import "elements-kit/ui/styles/accent/iris.css";

import "elements-kit/ui/avatar/avatar.css";

APICopy Anchor Link

<span class="x-avatar" data-size="3" data-variant="soft">
  <span class="x-avatar-fallback">WB</span>
  <img class="x-avatar-image" src="/wael.jpg" alt="" onerror="this.remove()" />
</span>

The fallback's own data-size picks how much of the box the text fills — a ratio, not a step off the type scale, so it holds at every avatar size:

<!-- default — sized for two initials -->
<span class="x-avatar" data-size="5">
  <span class="x-avatar-fallback">WB</span>
</span>

<!-- one letter, filling more of the box -->
<span class="x-avatar" data-size="5">
  <span class="x-avatar-fallback" data-size="3">W</span>
</span>

<!-- three letters, filling less -->
<span class="x-avatar" data-size="5">
  <span class="x-avatar-fallback" data-size="1">WBX</span>
</span>

There is no character-count selector in CSS, so the ratio is the author's to pick — but the count is known wherever the initials are produced, so it usually falls out of the same expression. Override --avatar-fallback-scale directly for a ratio between the three.

The computed size is floored at --font-size-1, so the smallest avatars stay legible rather than following the ratio down to unreadable text. One consequence: three letters do not fit a data-size="1" avatar at any legible size — 12px text needs roughly 28px of width in a 24px box — and get clipped. Use data-size="3" or larger for three-letter fallbacks, or an icon.

An <svg> in the fallback ignores the type scale and is sized to 60% of the avatar box instead, so a generic person glyph works at every data-size:

<span class="x-avatar" data-size="4">
  <span class="x-avatar-fallback">
    <svg viewBox="0 0 64 64" aria-hidden="true" style="fill: currentColor">
      <path d="…" />
    </svg>
  </span>
</span>

Fallback behaviorCopy Anchor Link

Both layers are absolutely positioned; .x-avatar-image sits above the fallback via z-index. It hides itself whenever it has nothing to paint:

.x-avatar-image:where(:not([src]), [src=""], [data-status="error"]) {
  display: none;
}

So there are three cases, and only one of them needs script:

A broken <img> that stays visible is not invisible — every engine paints its own artifact over the fallback:

No CSS suppresses all three, so flag the image on error. How, depends on who owns the DOM:

<!-- Static HTML — shortest thing that works -->
<img class="x-avatar-image" src="/wael.jpg" alt="" onerror="this.remove()" />

// Vanilla + strict CSP — one delegated listener, no inline handler.
// `error` does not bubble, so capture it.
document.addEventListener(
  "error",
  (event) => {
    const img = event.target;
    if (img instanceof HTMLImageElement && img.matches(".x-avatar-image")) {
      img.dataset.status = "error";
    }
  },
  true,
);

// React / Vue / Svelte — render the attribute, never mutate the node.
// `this.remove()` leaves the vdom believing the <img> is still mounted, and
// the next re-render puts it back.
const [failed, setFailed] = useState(false);

<img
  class="x-avatar-image"
  src={src}
  alt=""
  data-status={failed ? "error" : undefined}
  onError={() => setFailed(true)}
/>;

Setting the attribute is preferable to removing the element in every context that re-renders: it is non-destructive, so a retry or a changed src can clear it.

Keep alt="" whichever tier you use — the initials are decorative and the name belongs on the root, see Accessibility.

SizingCopy Anchor Link

Sizes 6–9 are pixel values multiplied by --scaling, so data-scaling on an ancestor still applies. Fallback type and icon size derive from the box, so they follow automatically — only the box size and corner radius are enumerated here.

VariantsCopy Anchor Link

• soft (default) — tinted fallback background, accent text.
• solid — accent fill, high-contrast text.

The variant only paints the fallback; an avatar showing its image looks identical either way.

RadiusCopy Anchor Link

Corner radius scales with data-size and follows data-radius on any ancestor. data-radius="pill" makes avatars fully circular:

<div data-radius="pill">
  <span class="x-avatar" data-size="4">
    <span class="x-avatar-fallback">WB</span>
  </span>
</div>

Set it on the avatar itself for a one-off circle. Available values: none, small, medium, large, pill.

ThemingCopy Anchor Link

Switch the color on a single avatar with data-accent="<color>", or set it on any ancestor to theme the whole subtree. Deriving the accent from the user's name gives stable per-user colors:

<span class="x-avatar" data-accent="amber" data-variant="soft">
  <span class="x-avatar-fallback">AB</span>
</span>

Light/dark flips automatically via the .dark class on a parent — see Light & dark.

AccessibilityCopy Anchor Link

.x-avatar ships no role — it's a visual class. alt="" keeps the image out of the accessibility tree, so the accessible name belongs on the root when the avatar carries information:

Add unset when rendering the avatar as <a> or <button> to neutralise native styling. Initials in the fallback are decorative in every case — they duplicate a name that assistive tech should read in full.