Photo Mosaic

When to useCopy Anchor Link

• Opening a plan or an answer that is visual by nature: a trip, a dish, a place, an event, a venue.
• The agent has 1–5 real photos from a search or tool result.

When not to useCopy Anchor Link

• The agent doesn't have real image URLs. It must never invent or guess them.
• The user wants to browse or pick from many photos. Use a Slide Gallery.
• Each image is an option with its own title. Use Inspiration Cards.

How the agent should use itCopy Anchor Link

• Use it once, at the top of the reply. It sets the scene; the details follow in text or other components.
• Take every image src from a tool result or the host, never from memory. Only http(s) URLs and data:image/(png|jpeg|webp|svg+xml) load.
• Put the strongest photo first. It becomes the hero.
• Write real alt text that says what each photo shows. It's required.
• Keep tags to a few words each, at most 5, and only facts from the plan ("10 days", "Road trip").
• Lifecycle: photos are a snapshot, so it usually needs none. If src values are signed URLs that expire, set expiresAt to their expiry. When the agent replaces the plan, mark the old call superseded (supersededBy).

LayoutsCopy Anchor Link

The layout follows the number of photos. The whole mosaic is about 16:9 (aspect: "wide", a little taller on phones when there are three or more photos) or square (aspect: "square").

InteractionCopy Anchor Link

• Enlarge: clicking a photo opens it in a lightbox (a native <dialog>), with its caption below. Captions appear only there, never on the mosaic. The previous and next buttons and the arrow keys move between photos, and moves are announced politely ("Photo 2 of 5: …"). Escape, Close or a click on the backdrop returns focus to the photo that opened it.
• Broken images: a photo that fails to load, or whose src isn't allowed, becomes a neutral tile showing its alt text.
• Streaming: the three-photo layout shows placeholders from the first token, and photos fill in as they arrive. Photos load lazily.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/photo-mosaic.json

UsageCopy Anchor Link

The Photo Mosaic is display-only, so the tool can return immediately:

import { tool } from "ai"
import { photoMosaicTool } from "@/components/genui/photo-mosaic.schema"

const tools = {
  [photoMosaicTool.name]: tool({
    description: photoMosaicTool.description,
    inputSchema: photoMosaicTool.inputSchema,
    execute: async () => ({ shown: true }),
  }),
}

Render it through the Renderer under show_photos, or directly:

<PhotoMosaic
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : "ready"}
  onResult={track}
/>

onResult is optional and for analytics only. It fires each time a photo is enlarged, never locks the mosaic, and the agent doesn't need to answer it:

{ action: "open", index: 0 } // zero-based

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_photos", props }, { message }), and render the thread's UI messages with the Renderer.

SchemaCopy Anchor Link

Host props: status (streaming or ready), onResult and className.

SourceCopy Anchor Link