Skip to main content
Metric is the dashboard primitive — a big number with a label, and optionally a delta that shows how that number is trending. It handles the visual logic of trend arrows and sentiment colors automatically, so you can feed it raw data and get a polished KPI card without fiddling with icons or color classes. You provide the data; Metric provides the opinion about how it should look.

​
Basic Usage

At minimum, a Metric needs a label and a value. The label names the statistic, and the value is the headline number that catches the eye. Values can be strings or raw numbers — strings are displayed as-is, so you have full control over formatting. When the value comes from state, use reactive expressions with pipes to format it at display time. Here the raw number 42000000 becomes $42M by dividing, rounding, and wrapping in literal $ and M characters — no Python formatting needed.

​
Description

Add a description for extra context below the headline number. This is the right place for time ranges, data sources, percentile qualifiers, or any caveat that helps readers interpret the number correctly. Without it, a value like “142ms” could mean anything — with it, the reader knows exactly what they’re looking at.

​
Trend Indicator

Pass a delta to show a change indicator alongside the value. Metric automatically infers the trend direction and color from the delta’s sign: positive deltas get a green up arrow, negative deltas get a red down arrow.

​
Inverted Sentiment

The auto-inference assumes “up is good, down is bad,” which works for most metrics but breaks for things like response time, error rates, or costs — anything where going up is bad news. Override the automatic coloring by setting trend_sentiment explicitly. The arrow still points in the direction the number moved, but the color reflects whether that movement is good or bad. Here response time increased by 18ms. Without the override, a positive delta would get a green arrow. Setting trend_sentiment="negative" makes it red, correctly signaling that slower is worse.

​
KPI Row

The classic dashboard header: a row of Metric cards spanning the top of a page. Wrap each Metric in a Card for visual separation and use a Grid to give every card equal width. This pattern scales naturally — add or remove cards and the grid reflows without manual width calculations.

​
Dashboard Layout

Metrics work as the top row of a dashboard, with a chart below for detail. Use min_column_width on the Grid so the metric cards reflow naturally at any container width.

​
With Sparklines

Place a Sparkline as a sibling to CardContent inside the Card. Use pb-0 gap-0 on the Card to eliminate spacing below the metric, so the sparkline bleeds flush to the bottom edge.

​
API Reference

Metric Parameters

​
label
str
required
The metric name displayed above the value (e.g. "Revenue", "Active Users").
​
value
str | int | float
required
The headline number. Strings are displayed as-is, so pre-format with currency symbols, commas, or units as needed.
​
description
str | None
default:"None"
Optional text below the value for additional context like time ranges or data sources.
​
delta
str | int | float | None
default:"None"
Change indicator shown next to the value (e.g. "+23.4%", "-15", "+$2.3M"). When present, an arrow icon and sentiment color are automatically inferred from the sign.
​
trend
str | None
default:"None"
Arrow direction: "up", "down", or "neutral". Inferred from delta when omitted — positive deltas point up, negative point down.
​
trend_sentiment
str | None
default:"None"
Color control: "positive" (green), "negative" (red), or "neutral" (muted). Inferred from trend when omitted — up is positive, down is negative. Override this for inverted metrics where down is good (e.g. costs decreasing).
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

​
Protocol Reference

Metric
{
  "type": "Metric",
  "label": "string (required)",
  "value": "number | number | string (required)",
  "description?": "string",
  "delta?": "number | number | string",
  "trend?": "up | down | neutral",
  "trendSentiment?": "positive | negative | neutral",
  "cssClass?": "string"
}
For the complete protocol schema, see Metric.