Artifact Preview

1-- Monthly revenue report2-- Revenue, orders and average order value by month and region,3-- with month-over-month change. Refunds are netted out.4 5WITH paid_orders AS (6  SELECT7    o.id,8    o.region,9    DATE_TRUNC('month', o.paid_at) AS month,10    o.total_cents - COALESCE(r.refunded_cents, 0) AS net_cents11  FROM orders o12  LEFT JOIN (13    SELECT order_id, SUM(amount_cents) AS refunded_cents14    FROM refunds15    GROUP BY order_id16  ) r ON r.order_id = o.id17  WHERE o.status = 'paid'18    AND o.paid_at >= DATE_TRUNC('month', CURRENT_DATE) - INTERVAL '12 months'19),20 21monthly AS (22  SELECT23    month,24    region,25    COUNT(*) AS orders,26    SUM(net_cents) / 100.0 AS revenue27  FROM paid_orders28  GROUP BY month, region29)30 31SELECT32  month,33  region,34  orders,35  ROUND(revenue, 2) AS revenue,36  ROUND(revenue / NULLIF(orders, 0), 2) AS avg_order_value,37  ROUND(38    100.0 * (revenue - LAG(revenue) OVER w) / NULLIF(LAG(revenue) OVER w, 0),39    140  ) AS revenue_change_pct41FROM monthly42WINDOW w AS (PARTITION BY region ORDER BY month)43ORDER BY month DESC, revenue DESC;

When to useCopy Anchor Link

• The agent generated or found a file the user will inspect, keep or share: a PDF, an image, a script, a CSV export, a JSON response, a Markdown doc.
• The user asked to export or download something.

When not to useCopy Anchor Link

• A short snippet answers the question. Put it in a code block in the reply.
• The data is for reading in the chat, not a file. Use a Data Table or an Article.
• The agent doesn't have the file's real content or URL. It must never invent either.

How the agent should use itCopy Anchor Link

• src and content come from a tool result. Never write a file's content from memory as if it were the real file.
• Send the whole content. Every line and up to 200 CSV rows are shown, with the preview scrolling inside its frame.
• Pick the kind that matches the file: csv for comma-separated data, json for JSON, code for source files with language set.
• Keep summary to one line and don't repeat the file name. It's read to screen readers (and is the image's alt text), not shown: say what the file is in the reply.
• Lifecycle: a file is a snapshot, so it usually needs none. When a newer version replaces it, set supersededBy on the old call. When src is a signed URL that expires, set expiresAt to its expiry.

How it worksCopy Anchor Link

• Header: the name and one meta line (PDF · 4 pages · 212 KB · v2). The size is computed from content when sizeBytes is omitted. When the file has no view switch (code, text, PDF), its icon buttons (wrap, expand) sit at the right of the meta line rather than on a row of their own.
• View switch: CSV, JSON, Markdown and images get a toolbar row with a full-width segmented control (Table / Raw, Tree / Raw, Preview / Raw, Fit / 100%), with the icon buttons after it.
• Preview: capped at about 480px with its own scroll. Any edge with more content past it fades: the sides into the preview's own surface, the top and bottom into the card (black in dark mode, white in light), so more lines above or below read without a scrollbar. The top fade starts under a CSV table's sticky header. Expand (an icon button) opens the same view in a native <dialog> (Escape or Close returns focus to the Expand button). View settings, column order and sort carry over between the two.
• Code surface: code, raw views and the JSON tree sit on their own grey surface (a clear grey on dark cards, a faint one on light), with the line-number gutter matching it.

• Footer actions (a closed set, in a fixed order): Open (an icon button; a new tab) and Download. Every file whose text is in the call also gets Copy (hollow, before Download), which shows "Copied" for a moment and reports { action: "copy" }. Download uses the file's URL with a download attribute, or builds the file from content. Actions that can't work are hidden: Open without an http(s) or blob: URL. A host can pass link to put its own main action in the footer instead of Download, such as a link to a details page.
• Syntax colours follow editor conventions: keywords and JSON keys blue, functions teal, strings green, numbers orange, true/false/null rose, comments and punctuation muted. Each is a darker step on light cards and a lighter one on dark, at least 4.5:1 against the code surface.
• Streaming: the header fills in first. The preview stays a skeleton until the call finishes, so a half-received CSV or JSON is never parsed, and the actions are disabled until then.
• It never locks. Copy, download and open can be used any number of times.

SafetyCopy Anchor Link

• src must be an http(s) URL, a blob: URL from an http(s) page, or a data: URL whose MIME type matches the kind (for example image/png for an image, text/csv for a CSV). A javascript: URL, a relative path or a data: URL of another type is ignored.
• Open is limited to http(s) and blob: URLs; data: URLs are never opened as pages.
• Markdown is parsed by a small tokenizer and rendered as React elements, never injected as HTML. Only http(s) links become links; anything else renders as its text. Markdown images show their alt text and are never loaded.
• The JSON parser builds its own tree, so keys like __proto__ are plain data.
• External links open in a new tab with rel="noopener noreferrer nofollow". Download file names are stripped of paths and reserved characters.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/artifact-preview.json

UsageCopy Anchor Link

import { tool } from "ai"
import { artifactPreviewTool } from "@/components/genui/artifact-preview.schema"

const tools = {
  [artifactPreviewTool.name]: tool({
    description: artifactPreviewTool.description,
    inputSchema: artifactPreviewTool.inputSchema,
  }),
}

Nothing goes back to the agent, so give the tool an execute that returns immediately. onResult reports the file actions, for analytics:

<ArtifactPreview
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : "ready"}
  onResult={(r) => track("artifact_action", r)} // { action: "download" | "open" }
/>

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

The preview never locks, so there is nothing to restore: render it from its stored input.

SchemaCopy Anchor Link

Host props: status (streaming or ready), onResult, link ({ label, href }, replaces Download), result and className.

SourceCopy Anchor Link