Insight Card

When to useCopy Anchor Link

• You have one personal insight from the user's own data worth a glance: where their money went, how often they went somewhere, how close they are to a budget, a streak, how many steps are left before a milestone.
• A tiny visual makes the sentence land faster than numbers alone.

When not to useCopy Anchor Link

• The user wants to explore or compare a series over time. Use a Chart.
• There are many records to read. Use a Data Table.
• The insight isn't backed by the user's data. Don't invent one.

How the agent should use itCopy Anchor Link

• State one insight in one short sentence that adds to the visual, and wrap the key figures in **double asterisks**. Don't repeat what the visual already shows. Nothing else is parsed.
• Every number in the sentence must come from the visual's data. Sums and counts of it are fine; estimates are not.
• Pick the visual for the question: bubbles for a split of spend, dot-calendar for visits in a month, progress for a budget or goal, compare for this period vs last, streak for a daily habit, sequence for logged steps toward a milestone (meals before a weigh-in, doses, sessions).
• For a streak, pass count when it began before the days shown (say, an 8-day streak with this week's 5 days).
• Keep bubbles to about 6, and fold the long tail into one item with other: true.
• Set locale to the user's locale, and weekStart to their week.

VisualsCopy Anchor Link

InteractionCopy Anchor Link

The action link and the share button send a result each time they're pressed. An action with kind: "open" is a round arrow button at the bottom right, named by its label (also shown as a tooltip); details and transactions are text links. The card never locks, because there's nothing to decide: it's an insight with a way into the data behind it. The action is a closed set, so the agent can't wire arbitrary behavior; the host maps each kind to a screen.

AccessibilityCopy Anchor Link

Each visual is a figure with a summary (aria-label), and its data is in a visually hidden table or list, or in visible text. Bubbles, and calendar days with a label, are buttons named with their label and value: hover, focus or tap shows the tooltip, and Escape hides it. Other dots aren't tab stops. The sequence is read as "6 of 8 done" followed by a list ("Monday breakfast done, …, 2 to go"). The streak is read as "Streak: 8 days" followed by a list ("Monday done, …, Friday not yet"), with today marked aria-current="date". The SVG, bars and circles are hidden from screen readers.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/insight-card.json

UsageCopy Anchor Link

import { tool } from "ai"
import { insightCardTool } from "@/components/genui/insight-card.schema"

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

When the user presses the action link or share, the agent (or your host) receives:

{ action: "details" } // or "transactions", "open", "share"

Render it directly, mapping results to your app's screens:

<InsightCard
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : "ready"}
  onResult={(r) => (r.action === "share" ? shareInsight(part) : openScreen(r.action))}
/>

With LangGraphCopy Anchor Link

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

Restoring from historyCopy Anchor Link

There's no finished state to restore. Render the stored tool input again; the card stays live.

SchemaCopy Anchor Link

format is number (default) or currency, with an ISO 4217 currency.

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

SourceCopy Anchor Link