Image

npx shadcn@latest add "@assistant-ui/image"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

Image renders one image message part: a preview that click-zooms into a fullscreen view, a loading placeholder while the pixels arrive, and an error state when generation is blocked. With a runtime it renders straight from a message's image part; standalone you hand it the part yourself.

Getting started

import { Image } from "@/components/assistant-ui/elements/image";
import { MessagePrimitive } from "@assistant-ui/react";

function AssistantMessage() {
  return (
    <MessagePrimitive.Root>
      <MessagePrimitive.Parts components={{ Image }} />
    </MessagePrimitive.Root>
  );
}

import { Image } from "@/components/assistant-ui/elements/image";

export function Picture() {
  return (
    <Image
      type="image"
      image="https://example.com/photo.png"
      filename="photo.png"
      status={{ type: "complete" }}
    />
  );
}

Anatomy

<div data-slot="image-root" data-variant={variant} data-size={size}>
  {/* status.type === "running": */}
  <div data-slot="image-generating" />

  {/* status.type === "incomplete" && status.reason === "content-filter": */}
  <div data-slot="image-content-filter-error" />

  {/* otherwise: */}
  <div className="aui-image-zoom-trigger" role="button" aria-label="Click to zoom image">
    <div data-slot="image-preview">
      <div data-slot="image-preview-loading" /> {/* until loaded or errored */}
      <img /> {/* or, on error: */}
      <div data-slot="image-preview-error" />
    </div>
  </div>
  <span data-slot="image-filename" /> {/* omitted when there is no filename */}
  <div data-slot="image-source" /> {/* optional attribution footer */}
</div>

The three top-level states are exclusive and resolve from status: running shows the generating placeholder and the filename, incomplete with reason content-filter shows only the blocked-image message, and everything else (including no status) shows the real preview. Clicking the preview, or pressing Enter or Space while it has focus, opens the image in a fullscreen dialog: a portal overlay with a focus trap, Escape-to-close, click-outside-to-close, and the page scroll locked while it is open. Space activation prevents page scrolling. ImageActions (download, copy, regenerate) and ImageSource are not part of the default render tree; add them yourself, as shown below.

Examples

Attribute a tool result

Compose the image parts when a tool returns its own image and source metadata. ratio gives the preview a stable frame while it loads, and fit="cover" crops the image to fill that frame. Use fit="contain" when every pixel matters.

import { Image } from "@/components/assistant-ui/elements/image";

type ImageToolResult = {
  imageUrl: string;
  source: {
    label?: string;
    url?: string;
    iconUrl?: string;
  };
};

function ToolImage({ imageUrl, source }: ImageToolResult) {
  return (
    <Image.Root>
      <Image.Zoom src={imageUrl}>
        <Image.Preview src={imageUrl} ratio="16:9" fit="cover" />
      </Image.Zoom>
      <Image.Source {...source} />
    </Image.Root>
  );
}

Image.Source uses label, or the URL host when no label is supplied. A safe URL makes the label a new-tab link. Give it iconUrl to show a 16px favicon; without one, it uses the source initial.

Add download, copy, and regenerate actions

ImageActions renders a download button and a copy-to-clipboard button; passing onRegenerate adds a third button that shows a spinner while it runs. Download picks a file extension from the image's MIME type (defaulting to .png) and uses part.filename when set; copy requires a browser with the Clipboard API and silently no-ops if it is unavailable or the write fails.

import { Image } from "@/components/assistant-ui/elements/image";

function ImageWithActions(part: React.ComponentProps<typeof Image>) {
  return (
    <Image.Root>
      <Image.Zoom src={part.image}>
        <Image.Preview src={part.image} />
      </Image.Zoom>
      <Image.Actions part={part} onRegenerate={() => refetchImage(part)} />
    </Image.Root>
  );
}

Variants and sizes

variant and size are props of Image.Root. Image itself renders the defaults.

<Image.Root variant="ghost" size="lg">
  <Image.Preview src={part.image} />
</Image.Root>

API reference