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
In queue…
Variations
In queue…
In queue…
In queue…
In queue…
Installation
- 1
Run the following command
npx shadcn@latest add https://localhostui.com/r/image-gen.json
Status lifecycle
- queued — fixed-ratio frame, grain, and an “In queue…” pill.
- generating — animated grain at ~24fps with a slow diagonal light sweep, a progress bar on the bottom edge, a percentage chip and ETA.
previewSrcframes crossfade in, getting sharper as progress rises. - 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. - error — grain freezes and desaturates, the frame shakes once, and a Retry button appears.
Reveal modes
| Mode | Effect |
|---|---|
radial | A circle expands from the center (clip-path: circle()) |
wipe | Top-to-bottom wipe (clip-path: inset()) |
fade | Opacity 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
| Prop | Type | Default | Description |
|---|---|---|---|
prompt* | string | — | Used for alt text, the live aria-label and Copy prompt. |
status | "queued""generating""done""error" | "queued" | Lifecycle. |
progress | number | — | 0..100. Omit for an indeterminate bar. |
src | string | — | Final image. It is decoded before the reveal starts, so it never half-loads on screen. |
previewSrc | string | — | 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. |
eta | number | — | Seconds remaining, shown under the percentage. |
ImageGenGrid
| Prop | Type | Default | Description |
|---|---|---|---|
items* | (ImageGenProps & { id?: string })[] | — | One ImageGen per cell. Cells enter 200ms apart. |
columns | 1 | 2 | 3 | 4 | 2 | Columns (3 and 4 collapse to 2 on small screens). |
selected / onSelect | number | 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.