Usage Chart

When to useCopy Anchor Link

• The user asks how much of something they've used over a period (API tokens, energy, data, minutes, spend) and you have it per day from a tool.
• The answer is a running picture: the shape of the days and what the period adds up to, with the chance to check any point in between.

When not to useCopy Anchor Link

• The user wants a trend of a rate or a score, or compares categories. Use a Chart.
• You have one total, not days. Say it in a sentence or use a KPI Card.
• The figures are a forecast or an estimate you made. Only show what the tool returned.
• There are fewer than 2 days.

How the agent should use itCopy Anchor Link

• Pass one row per day exactly as the tool returned them, in any order. Never total, average or fill gaps yourself: the card does the sums, so a figure on screen is always the data's, not the model's.
• Plot one quantity. Add an overlay only for a true part of it (cached of total tokens), never a different measure. The overlay shares the scale, and a day without it can leave the field out.
• Pick 1–3 stats the user would ask next. Each names a row field and how the days combine: sum for totals and costs, average for daily rates, max or min for extremes, latest for a level. A stat may read a field that isn't plotted, like a cost column.
• Name the value in 1–2 words, with format, currency or unit.
• In summary, say what stands out (the busiest day, a jump) in plain words.

DesignCopy Anchor Link

• Scrub to total. Moving across the chart puts a cursor on a day, dims the days after it and shows that day's value (and the overlay's) in a hover card. The date range under the title and every figure under the chart recalculate for the period from the first day up to the cursor. Leaving the chart returns to the whole period.
• Steps, not slopes. Each day holds its value across its own band, so a day reads as one flat run. Days are spaced evenly, in date order, whether or not the dates are consecutive.
• Grey and one accent. The main series uses the one-hue ramp and the overlay is the blue from the series palette. The legend under the chart names both, so colour is never the only key.
• Figures are abbreviated from four digits up (511.2K, 5.65M); money stays exact below 100,000.
• A day with no overlay value shows a dash in the hover card.

AccessibilityCopy Anchor Link

The plot is a slider: Left and Right step one day, Page Up and Page Down a week, Home and End jump to the ends, Escape returns to the whole period. Its value text reads the day, its values and the recalculated figures. The drawing is hidden from screen readers; a visually hidden table lists every day. Touch scrubs horizontally and still scrolls the page vertically. Dates are read as UTC days, so a day never shifts with the viewer's time zone, and numbers and dates follow the user's locale.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/usage-chart.json

UsageCopy Anchor Link

The Usage Chart is display-only, so the tool can return immediately:

import { tool } from "ai"
import { usageChartTool } from "@/components/genui/usage-chart.schema"

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

Render it through the Renderer under show_usage, or directly:

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

Days render as they stream in.

SchemaCopy Anchor Link

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

SourceCopy Anchor Link