KPI Card

When to useCopy Anchor Link

• The user asks how a business or finance number is tracking, from a connected tool: sales this week, what's left on a loan, where transactions went this month, revenue this year.
• One headline figure with a small breakdown answers it at a glance.

When not to useCopy Anchor Link

• The user wants to explore a series or compare several over time. Use a Chart.
• There are many records to read. Use a Data Table.
• It's one personal insight in a sentence. Use an Insight Card.
• The numbers aren't from the user's data. Don't invent them.

How the agent should use itCopy Anchor Link

• Every number must come from the tool result. Totals and shares computed from it are fine; estimates are not.
• Pick the visual for the question: segments for a split of a total, dots for installments or quotas (N of M), treemap for shares of spend by category, bars for a value per period with one highlighted.
• Only add periods when you have data for each. Key every block in data by its period key, or put a single block under default.
• Keep segments and legend rows in the same order, at most 5. Treemap tiles: at most 10, with shares summing to about 100.
• Deltas are in percent units (2.6 is +2.6%) with a short deltaLabel, e.g. "vs last week". The label is read by screen readers; visually the period switch already gives the context.
• Add the action only when the host can open the source data.

VisualsCopy Anchor Link

PeriodsCopy Anchor Link

With periods, the header shows a segmented switch (one pressed button at a time). Switching re-renders the block for that period: numbers roll to their new values, segment and bar sizes animate, and the treemap re-lays out. The switch is local to the card and never sent to the agent, but the current period is included when the user presses the header action.

InteractionCopy Anchor Link

The header's arrow button sends a result each time it's pressed. The card never locks: it's a view of the data with a way into the source. kind is a closed set, so the agent can't wire arbitrary behavior; the host maps it to a screen.

LocalesCopy Anchor Link

Numbers, currency and percentages are formatted with Intl in locale (default en-US). With de-DE, for example, values read "15.243,23 $". Values roll digit by digit only when the roller can reproduce Intl's text exactly; otherwise they change without the animation. The card's built-in words ("Forecast", "Other") are in English.

AccessibilityCopy Anchor Link

Each visual is a figure with a summary (aria-label) and a visually hidden table of its data; the drawn shapes are hidden from screen readers. Rolling numbers keep the real value in a visually hidden span. Deltas show a sign, an arrow and text, and are read as "Up 2.6% vs last week"; color is never the only cue. Treemap text color is picked per fill for at least 4.5:1 contrast in both themes. The period buttons use aria-pressed inside a labelled group, and the footer is a polite live region, so the new total is announced after a switch.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { kpiCardTool } from "@/components/genui/kpi-card.schema"

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

When the user presses the header's arrow button, the agent (or your host) receives:

{ action: "details", period: "weekly" } // or "open"; period only with periods

Without an action the card is display-only, so give the tool an execute that returns immediately. Render it directly, mapping results to your app's screens:

<KpiCard
  {...part.input}
  status={part.state === "input-streaming" ? "streaming" : "ready"}
  onResult={(r) => openScreen(r.action, r.period)}
/>

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_kpis", 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 and opens on defaultPeriod.

SchemaCopy Anchor Link

format is currency (with an ISO 4217 currency), number or percent. Percent values and deltas are in percent units: 12.5 is 12.5%.

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

SourceCopy Anchor Link