Pixel art, someone on a rooftop ledge at night, lit by their phone

Image Generation

New

A frame for an image that is still being made: a grid of tiny dots that swell around the cursor, take on the picture's colors and dissolve into the finished image.

Requested by @itsahmadali

Install it in one line

Available in v1.7.0

npx devignerui add image-generation

Writes components/ui/image-generation.tsx and lists what it needs.

First time here

npx devignerui init

Or by hand

Needs React 18 or 19 and Tailwind CSS v4.
Install the dependencies.
npm i cn motion @devigner-ui/icons devignerui thinking-orbs
Paste the source from into components/ui/image-generation.tsx.

Usage

import { ImageGeneration } from "@/components/ui/image-generation";

export function Example() {
  return (
    <ImageGeneration
      status={status}
      src={url}
      prompt="Pixel art, someone on a rooftop ledge at night, lit by their phone"
      focus={{ x: 86, y: 37 }}
      download="rooftop.jpg"
    />
  );
}

Custom composition

<ImageGeneration status="error" aspectRatio="16 / 9" onRetry={retry} className="max-w-md" />

Wired to a generation request

Shows each stage the server reports, then the finished image, with a retry on failure.

import { useState } from "react";
import {
  ImageGeneration,
  type ImageGenerationStatus,
} from "@/components/ui/image-generation";

export function Generator({ prompt }: { prompt: string }) {
  const [status, setStatus] = useState<ImageGenerationStatus>("queued");
  const [url, setUrl] = useState<string>();

  async function run() {
    setStatus("generating");
    try {
      const res = await fetch("/api/generate", {
        method: "POST",
        body: JSON.stringify({ prompt }),
      });
      const { image } = (await res.json()) as { image: string };
      setUrl(image);
      setStatus("refining");
      setTimeout(() => setStatus("complete"), 1200);
    } catch {
      setStatus("error");
    }
  }

  return (
    <div className="flex flex-col items-start gap-3">
      <button type="button" onClick={run}>
        Generate
      </button>
      <ImageGeneration
        status={status}
        src={url}
        prompt={prompt}
        onRetry={run}
      />
    </div>
  );
}

Wide frame

A 16:9 frame with no status line.

import { ImageGeneration } from "@/components/ui/image-generation";

export function Banner({ src }: { src?: string }) {
  return (
    <ImageGeneration
      status={src ? "complete" : "generating"}
      src={src}
      aspectRatio="16 / 9"
      showStatus={false}
      className="max-w-xl"
    />
  );
}

Every prop

statusgenerating

"queued" | "generating" | "refining" | "complete" | "error"

Where the generation is. The dots are faint while queued, full strength while generating, grow and take the image's colors while refining, and fade into the image when complete.

src-

string

URL of the generated image. Shown when complete, and its colors tint the dots while refining. From another domain, set crossOrigin for the colors.

children-

ReactNode

Your own media (Next Image, video) shown instead of an img of src. Pass tintSrc or src as well to keep the tinted dots.

tintSrcsrc

string

Image the dots take their colors from, such as a small thumbnail, so the full image isn't downloaded just for its colors.

crossOrigin-

"anonymous" | "use-credentials"

CORS mode of the img of src and of the color read, kept the same so the image is fetched once. Set "anonymous" for an image on another domain served with CORS headers.

prompt-

string

The prompt, shown in small text under the status line.

labelstatus text and prompt

string

Accessible name of the image frame, read by screen readers.

aspectRatio1 / 1

string

Shape of the frame, as a CSS aspect-ratio such as "16 / 9".

focus{ x: 50, y: 50 }

{ x: number; y: number }

The point of the image kept in view when the frame crops it, in percent like object-position. The tinted dots follow the same crop.

interactivetrue

boolean

Lets a mouse swell and gently part the dots around it, and a click send a small ripple through them, while the image is in progress.

statusText-

Partial<Record<status, string>>

Replaces the built-in status text per status, such as { generating: "Drawing" }. Statuses left out keep the English default.

showStatustrue

boolean

Shows the status line with its icon under the frame.

onRetry-

() => void

Shows a Try again button under the frame when status is "error", and is called when it is pressed.

retryLabelTry again

string

Text of the retry button.

download-

boolean | string

Shows a download icon button in the frame's top-right corner when status is "complete" and src is set. A string is the saved file's name; true takes the name from the end of src.

downloadLabelDownload

string

Accessible name and tooltip of the download button.

classNames-

ImageGenerationClassNames

Slot classes: frame, media and status.

How to use it

The live demo plays one generation on a loop: a still grid of tiny dots fills the frame, faint while queued and full strength while generating, then the dots grow and take on the colors of the picture while refining, and finally grow into each other and fade as the sharp image comes in. Move the mouse over the grid and the dots around it swell and part a little; click to send a small ripple through them.

When to use it

The result slot of an AI image tool, from the moment the request is sent until the image arrives.
Any long job that ends in a picture, such as a render, an upscale or a thumbnail being made on the server.
Progress reported in a few steps (queued, generating, refining) rather than as a percentage.

When to reach for something else

A plain image that is only loading over the network. Use a skeleton or the browser's own lazy loading.
Showing an exact percentage or time left. The swarm shows the stage, not how far along it is.
Long grids of many results at once. Frames share one animation loop and one theme watcher, but each still draws its own canvas; a few on screen are fine, dozens moving together are not.

Keyboard

Tab: Focuses the Try again button when status is "error" and onRetry is set, or the download button when status is "complete" and download is set. The frame itself is not focusable.
Enter / Space: Presses Try again or download.

Accessibility

The frame has role="img" and is named by label, or by the status text and prompt ("Generating image: Glass spheres...").
The root has aria-busy while the status is queued, generating or refining.
A visually hidden aria-live="polite" region holds the status text, so each new status is read out once, even with showStatus off. The visible status line is aria-hidden so it isn't read twice.
The canvas, the media layer and the status icon are aria-hidden. The status is always written out in text, so neither color nor motion is the only signal.
Try again is a real <button type="button"> with a focus ring in the ring color. It appears without taking focus, so a failure never pulls a keyboard user away from where they are; the live region announces it.
Download is an icon-only <button type="button"> over the frame's top-right corner, named by downloadLabel ("Download") with the same text as a tooltip and the same focus ring. It sits outside the role="img" frame so screen readers reach it, and also appears without taking focus.
A prompt cut with an ellipsis shows in full as a tooltip on hover.
Honors prefers-reduced-motion and an ancestor <MotionConfig reducedMotion="always">, so an in-app motion switch works too. Under reduced motion the dots jump straight to each state's size and color, the pointer neither swells nor moves them, a click sends no ripple and the status icon stands still.

Theming

The frame is bg-muted with rounded-xl corners; extra classes go through classNames.frame.
The dots are drawn in the canvas's text color: the foreground token, or the destructive token when status is "error". They are read again whenever the class or data-theme attribute of <html> or the system color scheme changes, so a theme switch recolors them without a reload.
The status mark sits in a 36px cell with no background: a 32px thinking orb while the job is in progress, a tick when complete, and an alert in the destructive color on error.
While refining, each dot takes the color of the image under it, rounded to 4 bits a channel.
The status line is text-foreground, text-destructive on error; extra classes go through classNames.status.

Edge cases

The dots sit on a hex grid that fills the frame, 12px apart, so a bigger frame has more of them.
The canvas follows the frame's size; a resize, or moving the window to a screen with another pixel ratio, lays the dots out again where the current state wants them.
The animation stops by itself once every dot has settled, and pauses while the frame is scrolled out of view.
Coloring the dots needs to read the image's pixels. For an image from another domain, set crossOrigin="anonymous" and serve it with CORS headers (Access-Control-Allow-Origin); without them the dots stay one color and the image still shows when complete. The img of src uses the same mode, so the image is downloaded once.
Colors are read only once the image has loaded, so the dots never flash black on the way. Transparent parts of an image leave their dots in the ink color.
children replace the img of src as the visible media, so a Next Image works. The dots only take image colors when tintSrc or src is set as well; a small tintSrc thumbnail saves downloading the full image just for its colors. children that render nothing, such as {ready && <Image />} before it is ready, count as no media.
Once the image is in progress no longer (complete or error), the dots stop catching the pointer, so a right-click, long-press or drag reaches the finished image.
With no src and no children, complete leaves the tiny dots in place instead of fading them, since there is nothing to show under them.
On error a small ripple runs out from the middle, then the dots settle back and dim to 45%. The image, if any, shows faintly and blurred, scaled a touch so the blur keeps clear of the frame's edges.
If the pointer is over the frame when the status leaves the in-progress states, the swell around it lets go instead of staying where the cursor was.
The grid never moves on its own; only the pointer moves dots off their places. A mouse or pen swells the dots within about a quarter of the frame's shorter side and gently parts the closest ones; a finger scrolls the page as usual. A click or tap sends a small ripple. None of this works once the status is complete or error.
Download fetches src and saves it under the download name, so it works for an image on another domain only when that domain sends CORS headers (Access-Control-Allow-Origin). Without them the image opens in a new tab instead, where it can be saved by hand. It needs src; with only children there is nothing to save, so the button stays hidden.
The frame is max-w-xs (320px) wide by default and its height follows aspectRatio. Pass a max-w-* or w-* class in className for another size.

Troubleshooting

The dots never take on the image's colors.

The image is on another domain, so the browser won't let the canvas read its pixels unless it is served with Access-Control-Allow-Origin and crossOrigin="anonymous" is set. Or serve it from your own domain. The dots also stay one color when only children is passed; set tintSrc or src too.

The frame is tiny or has no height.

The height comes from aspectRatio and the width from the parent, up to max-w-xs. Inside a flex row with no width, give it a w-* class.

The component renders with no background or the wrong colors.

Colors use the standard shadcn/ui tokens only (background, foreground, primary, secondary, muted, accent, border, input, ring, destructive), so a project set up with shadcn/ui needs nothing extra and the component follows its theme, dark mode included. Without shadcn/ui, define those CSS variables for :root and .dark and map them in your Tailwind v4 @theme, or run npx shadcn init.

Stuck on something else? Ask in the Discord.

Some of these designs take cues from interfaces we've admired around the web. If one started as your idea and you'd like credit, message us on X @devignerui or in the Discord and we'll add it.