use-image-status

Installation

Usage

useImageStatus preloads an image URL with new window.Image() and tracks a three-state machine: loading → success / failure. Use it to build any image-like component with skeleton and fallback slots — it is what Avatar and Image run internally.

import { useImageStatus } from "@/ui";

function Thumbnail({ src }: { src?: string }) {
  const status = useImageStatus(src);

  return (
    <div className="relative size-12 overflow-hidden rounded-md">
      {status === "loading" && <Skeleton className="size-full" />}
      {status === "failure" && <span className="text-xs text-muted-foreground">Failed</span>}
      {status === "success" && <img src={src} alt="" className="size-full object-cover" />}
    </div>
  );
}

Behavior details: an empty or undefined src resolves to failure immediately without touching the network; the state callbacks are wrapped in startTransition so a resolved load does not block input; and in-flight loads are cleaned up on src change or unmount (the onload / onerror handlers are detached and late events are ignored).

API Reference

Parameters

Returns