Skip to Content
kindui

Generated Image

Show an image the agent is making, from its progress and a blurred preview to the image, which opens full size.

Use a generated image when the agent makes a picture and you want to show it arriving in the conversation. It holds a frame of the image's shape the whole time, so the conversation never jumps: grain over a drifting field, then over a blurred preview that sharpens as it progresses, then the image dissolving in, or what went wrong.

Creating image0%
Watch the grain thin and the preview sharpen until the image dissolves in. Press the image, or focus it and press Enter, to view it full size, and Escape to close it. Press Replay to watch it again.

Installation

npx shadcn@latest add @kind-ui/generated-image

Composition

GeneratedImage
โ”œโ”€โ”€ GeneratedImageFrame
โ”‚   โ”œโ”€โ”€ GeneratedImagePreview
โ”‚   โ”œโ”€โ”€ GeneratedImageImage
โ”‚   โ”œโ”€โ”€ GeneratedImageProgress
โ”‚   โ”œโ”€โ”€ GeneratedImageError
โ”‚   โ”œโ”€โ”€ GeneratedImageTrigger
โ”‚   โ””โ”€โ”€ GeneratedImageDownload
โ”œโ”€โ”€ GeneratedImageBackdrop
โ””โ”€โ”€ GeneratedImageDialog
    โ”œโ”€โ”€ GeneratedImageFullImage
    โ”œโ”€โ”€ GeneratedImageTitle
    โ”œโ”€โ”€ GeneratedImageDownload
    โ””โ”€โ”€ GeneratedImageClose

GeneratedImage is a figure named by its alt. GeneratedImageFrame takes the image's shape and holds the rest: GeneratedImagePreview is the blurred preview, GeneratedImageImage the image at src, GeneratedImageProgress a UI SDK Progress, read as a quiet label in the corner while the image is on its way, and GeneratedImageError what went wrong. GeneratedImageTrigger covers the loaded image as View full size, and GeneratedImageDownload sits in its corner. GeneratedImageDialog shows GeneratedImageFullImage with the alt as its GeneratedImageTitle, Download and Close, over GeneratedImageBackdrop. To arrange the parts yourself, pass them as children of GeneratedImage.

Usage

From Generating to Loaded

Pass width and height, the image's size in pixels. The frame takes their shape before anything arrives and keeps it in every phase, so nothing around it moves.

Set status to "generating" while the image is being made. Until there's a preview, the frame is a soft field of the accent color under film grain. Pass preview, the URL of a partial image, when your model streams one: it shows heavily blurred and muted. Pass progress, from 0 to 100, when you know how far it has come: the grain thins and the preview sharpens toward it, and a label in the corner reads, for example, Creating image ยท 42%. Screen readers get the same value from the progress bar.

Once the image is made, set status to "ready" and src to its URL. The component then reads the image's own load and error: it shows Loading image until the image is in, then dissolves it in over the preview, grain first, as the last of the grain clears. Keep preview until then, so the frame never goes blank. The figure is aria-busy until the image loads.

<GeneratedImage
  alt="A lighthouse at dusk"
  status={image.url ? "ready" : "generating"}
  progress={image.progress}
  preview={image.partialUrl}
  src={image.url}
  width={1024}
  height={768}
/>

Errors

Set status to "error" when generation fails, with error saying why. An image at src that fails to load shows an error too. The frame keeps its size and shows a muted image glyph with the error, else "The image couldn't be generated." or "The image couldn't be loaded.".

For an image it saw being generated, the component announces "Image ready" when it loads or "Image failed" when it fails, once for each src. Images that were ready when they first rendered, like earlier ones in the conversation, stay quiet.

Full Size and Download

Press the loaded image, or focus it and press Enter or Space, to open it full size in a modal dialog titled by its alt. Escape, Close or a press outside closes it, and focus returns to the image. Pass defaultOpen, or open with onOpenChange, to open it yourself. The dialog closes if the image goes back to generating or fails.

Download shows while onDownload is set and the image has loaded: in the frame's corner on hover or focus, and in the dialog. The component never fetches the file: it calls onDownload, and your handler saves it, as the example's save does. Return a promise to keep Download pending until it settles; if it rejects, the component announces "Download failed".

Motion

At full motion the field drifts, the grain flickers while the image is on its way; the preview sharpens smoothly, the image dissolves in and settles, and the dialog rises in. Under prefers-reduced-motion, or with motion="reduced", the field and grain hold still, the preview sharpens in steps, and the image and dialog fade in over 120 ms. With motion="none" nothing animates.

API Reference

Prop

Type

Agent

An agent connected with createAgent finds the image by its alt and reads phase and open. open() is offered once the image has loaded and while the dialog is closed, close() while it's open, and download() while onDownload is set, the image has loaded and no download is pending. Like any component that opens, it also has UI SDK's generic press.

Prop

Type

Runs in React and Web Components. On <kind-generated-image>, the props are kebab-case attributes. The can-download attribute offers Download, which fires the download event, and onOpenChange is openchange. The element fills in its frame and dialog when it has no children.