ComponentsImage Generation

Image Generation

The placeholder and result frame for AI images — live grain while waiting, a progressive blur-to-sharp reveal, hover actions, a lightbox and a variations grid.

Preview

Variations

Installation

  1. 1

    Run the following command

    npx shadcn@latest add https://localhostui.com/r/image-gen.json
    

Status lifecycle

  1. queued — fixed-ratio frame, grain, and an “In queue…” pill.
  2. generating — animated grain at ~24fps with a slow diagonal light sweep, a progress bar on the bottom edge, a percentage chip and ETA. previewSrc frames crossfade in, getting sharper as progress rises.
  3. done — the image is decoded first, then resolves from blur(20px) scale(1.04) to sharp over 700ms while the radial, wipe or fade reveal plays and the grain fades out.
  4. error — grain freezes and desaturates, the frame shakes once, and a Retry button appears.

Reveal modes

ModeEffect
radialA circle expands from the center (clip-path: circle())
wipeTop-to-bottom wipe (clip-path: inset())
fadeOpacity only — also used with reduced motion

Examples

Polling an API (Replicate, fal)

const [job, setJob] = useState<{ status: ImageGenStatus; progress?: number; url?: string }>({ status: "queued" });

useEffect(() => {
  const id = setInterval(async () => {
    const res = await fetch(`/api/predictions/${predictionId}`).then((r) => r.json());
    if (res.status === "starting") setJob({ status: "queued" });
    if (res.status === "processing") setJob({ status: "generating", progress: res.progress * 100 });
    if (res.status === "succeeded") setJob({ status: "done", url: res.output[0] });
    if (res.status === "failed") setJob({ status: "error" });
    if (res.status === "succeeded" || res.status === "failed") clearInterval(id);
  }, 1000);
  return () => clearInterval(id);
}, [predictionId]);

<ImageGen {...job} src={job.url} prompt={prompt} />

Streaming partial images

APIs that stream partial frames (base64 or URLs) map straight onto previewSrc:

for await (const event of stream) {
  if (event.type === "partial_image") setPreview(`data:image/png;base64,${event.b64}`);
  if (event.type === "completed") setSrc(event.url);
}

<ImageGen status={src ? "done" : "generating"} previewSrc={preview} src={src} prompt={prompt} />

Variations grid

<ImageGenGrid columns={2} items={variations.map((v) => ({ ...v, prompt }))} onSelect={setPicked} />

Props

ImageGen

PropTypeDefaultDescription
prompt*string—Used for alt text, the live aria-label and Copy prompt.
status
"queued""generating""done""error"
"queued"Lifecycle.
progressnumber—0..100. Omit for an indeterminate bar.
srcstring—Final image. It is decoded before the reveal starts, so it never half-loads on screen.
previewSrcstring—Low-res intermediate frame. Blur = 16px × (1 − progress / 100).
aspectRatio
"1:1""4:3""16:9""9:16"
"1:1"Fixed frame ratio — no layout shift.
reveal
"radial""wipe""fade"
"radial"How the final image appears.
etanumber—Seconds remaining, shown under the percentage.

ImageGenGrid

PropTypeDefaultDescription
items*(ImageGenProps & { id?: string })[]—One ImageGen per cell. Cells enter 200ms apart.
columns1 | 2 | 3 | 42Columns (3 and 4 collapse to 2 on small screens).
selected / onSelectnumber | null / (index) => void—Selected cell gets a ring and the others dim to 60%. Double-click opens the lightbox.

Accessibility

  • While waiting, the frame is role="img" with a live label like “Generating image: a mountain lake, 45%”; when done it's a real <img alt={prompt}>.
  • Progress uses role="progressbar".
  • Overlay actions also appear on keyboard focus, not only on hover.
  • With reduced motion: static grain, a plain fade reveal and no lightbox morph.