Avatar

AB

ER

AB

GH

CN

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34

import { Div } from "@implementjs/core";
import { Avatar, AvatarFallback, AvatarImage } from "@/lib/components/ui/avatar";

export default function AvatarDemo() {
	return Div(
		{ class: "flex flex-row flex-wrap items-center gap-8" },
		Avatar(
			AvatarImage({ src: "https://github.com/ieedan.png", alt: "@ieedan" }),
			AvatarFallback("AB"),
		),
		Avatar(
			AvatarImage({ src: "https://github.com/broken-link-404.png/nope", alt: "broken" }),
			AvatarFallback("ER"),
		),
		Div(
			{
				class:
					"flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background *:data-[slot=avatar]:grayscale",
			},
			Avatar(
				AvatarImage({ src: "https://github.com/ieedan.png", alt: "@ieedan" }),
				AvatarFallback("AB"),
			),
			Avatar(
				AvatarImage({ src: "https://github.com/github.png", alt: "@github" }),
				AvatarFallback("GH"),
			),
			Avatar(
				AvatarImage({ src: "https://github.com/shadcn.png", alt: "@shadcn" }),
				AvatarFallback("CN"),
			),
		),
	);
}

An avatar renders an image with a fallback for when the image is loading or unavailable. Avatar is the root, AvatarImage is the picture, and AvatarFallback is what shows until the image has actually loaded (initials, an icon, anything).

import { Avatar, AvatarFallback, AvatarImage } from "@implementjs/primitives";

Avatar(AvatarImage({ src: "https://github.com/ieedan.png", alt: "@ieedan" }), AvatarFallback("AB"));

Each part accepts optional props and children — pass a props object when you need attributes, or pass children directly. See createComponent. Extra props are forwarded onto the underlying Div, Img, or Span.

Loading status

The root tracks a loading status: "loading", "loaded", or "error". The image is preloaded off-DOM, so the fallback stays visible until the browser has real pixels — no broken-image flash. The image is hidden until the status is "loaded", and the fallback is hidden once it is.

If src is missing or the request fails, the status becomes "error" and the fallback simply stays.

Pass onLoadingStatusChange to observe it:

Avatar(
	{ onLoadingStatusChange: (status) => console.log(status) },
	AvatarImage({ src }),
	AvatarFallback("AB"),
);

A reactive src re-runs the load: pass a signal and swapping the value puts the avatar back into "loading" until the new image resolves.

Delaying the fallback swap

On a fast connection the fallback can flash for a frame before the image appears. delayMs waits that many milliseconds after the image loads before showing it:

Avatar({ delayMs: 600 }, AvatarImage({ src }), AvatarFallback("AB"));

Styling

Every part sets a data-avatar-* attribute so you can target it in CSS, and all three expose data-status with the current loading status:

Avatar(
	{ class: "relative flex size-8 shrink-0 overflow-hidden rounded-full" },
	AvatarImage({ src, class: "aspect-square size-full" }),
	AvatarFallback({ class: "flex size-full items-center justify-center bg-muted" }, "AB"),
);

Visibility is handled for you with inline display, so a flex class on the fallback is safe — it only applies while the fallback is actually shown.

API Reference