# Generated Image (/docs/agent-ui/components/generated-image)

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.

<Example caption="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.">
<Basic />

```tsx
"use client";

import { useEffect, useState } from "react";
import { GeneratedImage } from "@/components/ui/generated-image";
import lighthouse from "./lighthouse.png";
import preview from "./lighthouse-preview.png";

function save() {
  const link = document.createElement("a");
  link.href = lighthouse.src;
  link.download = "lighthouse.png";
  link.click();
}

export default function GeneratedImageExample() {
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    if (progress >= 100) return;
    const timer = setTimeout(() => setProgress(progress + 5), 250);
    return () => clearTimeout(timer);
  }, [progress]);

  return (
    <div className="flex w-full max-w-md flex-col items-start gap-3">
      <GeneratedImage
        alt="A lighthouse at dusk"
        status={progress < 100 ? "generating" : "ready"}
        progress={progress}
        preview={progress >= 30 ? preview.src : undefined}
        src={lighthouse.src}
        width={lighthouse.width}
        height={lighthouse.height}
        onDownload={save}
        className="w-full"
      />
      <button type="button" className="text-sm underline" onClick={() => setProgress(0)}>
        Replay
      </button>
    </div>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/generated-image
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/generated-image-web
```

## Composition [#composition]

```text
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 [#usage]

### From Generating to Loaded [#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.

```tsx
<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 [#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 [#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 [#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 [#api-reference]

### GeneratedImageOptions

| Prop            | Type                                                                                     | Description                                                                                                                                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alt`           | `string`                                                                                 | Describes the image. Names it, and titles the full size view.                                                                                                                                                                                                  |
| `src?`          | `string \| undefined`                                                                    | The image's URL. Set it with, or before, `status` `"ready"`; until it's set the frame shows "Loading image".                                                                                                                                                   |
| `status?`       | `"error" \| "generating" \| "ready"`                                                     | `"generating"` while the image is being made, `"ready"` once `src` holds it, `"error"` when it failed. Any other value reads as `"ready"`. Default: `"ready"`                                                                                                  |
| `progress?`     | `number \| undefined`                                                                    | How far generation has come, from 0 to 100. The preview sharpens and the grain thins as it rises, and the corner reads it, like "Creating image · 42%". Without it, both stay where they start and the corner reads "Creating image".                          |
| `preview?`      | `string \| undefined`                                                                    | A partial image's URL while generating. It shows blurred, sharpening with `progress`, until the image loads.                                                                                                                                                   |
| `width?`        | `number \| undefined`                                                                    | The image's width in pixels. With `height`, it gives the frame its shape in every phase, so nothing moves when the image arrives. Default: `1024`                                                                                                              |
| `height?`       | `number \| undefined`                                                                    | The image's height in pixels. Default: `1024`                                                                                                                                                                                                                  |
| `error?`        | `string \| undefined`                                                                    | What went wrong, shown in the frame when `status` is `"error"` or the image fails to load.                                                                                                                                                                     |
| `onDownload?`   | `((details: GeneratedImageDownloadDetails) => unknown) \| undefined`                     | Called when Download is pressed. Shows Download while set. The host fetches and saves the file; return a promise to keep Download pending until it settles. If it rejects or throws, Download is offered again and the component announces "Download failed".  |
| `open?`         | `boolean \| undefined`                                                                   | Whether the full size view is open. Passing it controls it.                                                                                                                                                                                                    |
| `defaultOpen?`  | `boolean \| undefined`                                                                   | Whether the full size view opens by itself, when `open` isn't passed. It opens once the image loads. Default: `false`                                                                                                                                          |
| `onOpenChange?` | `((open: boolean, details: ChangeDetails<DialogOpenChangeReason>) => void) \| undefined` | Called when the full size view opens or closes, with what caused it.                                                                                                                                                                                           |
| `motion?`       | `"auto" \| "none" \| "reduced"`                                                          | At full motion the placeholder drifts and its grain flickers, the image settles in over it and the full size view rises in. Reduced motion holds the placeholder still and only fades, in 120 ms. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"` |

### Agent [#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`.

### GeneratedImageAgentActions

| Prop       | Type                                     | Description                                                                                            |
| ---------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `open`     | `(() => boolean) \| undefined`           | Opens the full size view. Offered while the image is loaded and the view is closed.                    |
| `close`    | `(() => boolean) \| undefined`           | Closes the full size view. Offered while it's open.                                                    |
| `download` | `((event?: Event) => void) \| undefined` | Calls `onDownload`. Offered while `onDownload` is set, the image is loaded and no download is pending. |

<Caption>
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.
</Caption>