Avatar

The Mishka Chelekom Headless Avatar is an image with a text fallback for Phoenix LiveView, with no styling of its own. Its Avatar hook tracks the image's loading status and keeps it on the root as data-status: idle when there is no src, then loading, then loaded or error. The image stays hidden until it has loaded. The fallback, usually initials, shows whenever the image is not loaded, after an optional delay so a fast image never flashes it.

The root takes class, the image takes image_class and the fallback takes fallback_class, so you style each part with your own Tailwind classes.

The first avatar loads a photo. The second has no src, so it shows its fallback straight away.

Base UI Avatar example (Phoenix headless)

LTR RTL

Preview

LT LT

Show the whole example Show less

<.avatar
  id="baseui-avatar-hero-1"
  src="https://images.unsplash.com/photo-1543610892-0b1f7e6d8ac1?w=128&h=128&dpr=2&q=80"
  alt="Lisa Turner"
  width="48"
  height="48"
  delay={600}
  class="inline-flex size-8 items-center justify-center overflow-hidden rounded-full bg-neutral-200 align-middle text-sm leading-none font-normal text-neutral-950 select-none dark:bg-neutral-800 dark:text-white"
  image_class="size-full object-cover"
  fallback_class="flex size-full items-center justify-center text-sm"
>
  LT
</.avatar>
<.avatar
  id="baseui-avatar-hero-2"
  class="inline-flex size-8 items-center justify-center overflow-hidden rounded-full bg-neutral-200 align-middle text-sm leading-none font-normal text-neutral-950 select-none dark:bg-neutral-800 dark:text-white"
  fallback_class="flex size-full items-center justify-center"
>
  LT
</.avatar>

The src below points at a file that does not exist. The request fails, the hook sets data-status="error", the image stays hidden and the fallback stays on screen.

Avatar example - image that fails to load (Phoenix headless)

LTR RTL

Preview

SH

Show the whole example Show less

<.avatar
  id="avatar-missing-image"
  src="/images/missing-avatar.png"
  alt="Sara Hosseini"
  class="inline-flex size-8 items-center justify-center overflow-hidden rounded-full bg-neutral-200 align-middle text-sm leading-none font-normal text-neutral-950 select-none dark:bg-neutral-800 dark:text-white"
  image_class="size-full object-cover"
  fallback_class="flex size-full items-center justify-center text-sm"
>
  SH
</.avatar>

id is required. src is the image address. Without it only the fallback renders, and the status stays idle. alt is the image's alternative text and defaults to an empty string, which marks the image as decorative. width and height go to the img as they are, and so do crossorigin and referrer_policy, which becomes referrerpolicy.

delay is the number of milliseconds the fallback waits before it appears. on_loading_status_change is a LiveView event pushed with %{"status" => status} on every status change, to the LiveView or LiveComponent that renders the avatar. Any global attribute, such as aria-label, lands on the root.

The default slot is the fallback. It is drawn only when the slot has content.

Each part carries a stable data-part and a structural chelekom-avatar__* class you can target, plus a status attribute on the root that drives the reveal and the fallback.

There is no formal WAI-ARIA APG pattern for avatars. The image has an empty alt by default, which marks it as decorative. Pass a meaningful alt when the avatar conveys information, for example a name that is not shown elsewhere on the page.