Image gallery

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

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>
  );
}

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

Image gallery groups several images a tool returned, such as search results or generated variants, into a compact grid without making the transcript heavy.

Getting started

"use client";

import {
  defineToolkit,
  type ToolCallMessagePartComponent,
} from "@assistant-ui/react";
import {
  ImageGallery,
  type GalleryImage,
} from "@/components/assistant-ui/elements/image-gallery";

type ImageSearchResult = { images: GalleryImage[] };

const ImageSearchToolUI: ToolCallMessagePartComponent<
  { query: string },
  ImageSearchResult
> = ({ result }) => <ImageGallery images={result?.images ?? []} />;

export const toolkit = defineToolkit({
  show_image_results: {
    type: "backend",
    render: ImageSearchToolUI,
  },
});

import { ImageGallery, type GalleryImage } from "@/components/assistant-ui/elements/image-gallery";

const images: GalleryImage[] = [
  {
    id: "redwood",
    src: "/results/redwood.jpg",
    alt: "Sunlight through a redwood grove",
    caption: "Generated landscape, variation 1",
  },
];

export function Results() {
  return <ImageGallery images={images} onOpen={(id) => console.log(id)} />;
}

Anatomy

<div data-slot="image-gallery">
  <button aria-label="Open image: Sunlight through a redwood grove">
    <img loading="lazy" />
  </button>
  <div role="dialog" aria-modal="true">
    <img />
    <div>Caption, source, counter, and image controls</div>
  </div>
</div>

The grid uses two columns and grows to three when its container has room. It shows six images by default. When there are more, the final visible tile reads +N and opens at that image rather than hiding the rest of the gallery. The dialog keeps its place with previous and next controls, ArrowLeft and ArrowRight, and Escape.

Examples

Show an overflow tile

Set maxVisible when the surrounding layout needs a smaller grid. The final visible tile remains the next image in order.

<ImageGallery images={images} maxVisible={3} />

Link image sources

An image can carry a caption and source. The source becomes an external link only for a safe http, https, mailto, or relative URL.

<ImageGallery
  images={[
    {
      id: "river",
      src: "/results/river.jpg",
      alt: "A river seen from above",
      caption: "Reference photograph",
      source: {
        label: "National Park Service",
        url: "https://www.nps.gov/",
      },
    },
  ]}
/>

API reference