;
};
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](/docs/concepts/expressions#formatting-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.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.app import PrefabApp
from prefab_ui.components import STATE as state, Metric
with PrefabApp(state={"revenue": 42_000_000}) as app:
Metric(label="Revenue", value=f"${(state.revenue / 1_000_000).round()}M")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "pf-app-root",
"type": "Div",
"children": [
{
"type": "Metric",
"label": "Revenue",
"value": "${{ revenue / 1000000 | round:0 }}M"
}
]
},
"state": {"revenue": 42000000}
}
```
## 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.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Metric
Metric(
label="Response Time",
value="142ms",
description="p95 over the last 24 hours",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "Metric",
"label": "Response Time",
"value": "142ms",
"description": "p95 over the last 24 hours"
}
}
```
## 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.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Card, CardContent, Metric, Row
with Row(gap=6):
with Card():
with CardContent(css_class="p-6"):
Metric(label="Revenue", value="$1.2M", delta="+12%")
with Card():
with CardContent(css_class="p-6"):
Metric(label="Units Sold", value="8,430", delta="-340")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-6",
"type": "Row",
"children": [
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [{"type": "Metric", "label": "Revenue", "value": "$1.2M", "delta": "+12%"}]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [{"type": "Metric", "label": "Units Sold", "value": "8,430", "delta": "-340"}]
}
]
}
]
}
}
```
## 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.
```python Python {10-11} icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Card, CardContent, Metric, Row
with Row(gap=6):
with Card():
with CardContent(css_class="p-6"):
Metric(label="Revenue", value="$1.2M", delta="+12%")
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Response Time",
value="284ms",
delta="+18ms",
trend="up",
trend_sentiment="negative",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-6",
"type": "Row",
"children": [
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [{"type": "Metric", "label": "Revenue", "value": "$1.2M", "delta": "+12%"}]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Response Time",
"value": "284ms",
"delta": "+18ms",
"trend": "up",
"trendSentiment": "negative"
}
]
}
]
}
]
}
}
```
## 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.
```python Python expandable icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Card, CardContent, Grid, Metric
with Grid(min_column_width="14rem", gap=4):
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Revenue",
value="$42M",
description="Year to date",
delta="+12%",
)
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Conversion",
value="3.2%",
description="Last 30 days",
delta="+0.4%",
)
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Avg. Order",
value="$128",
description="Per transaction",
delta="-$3",
trend="down",
trend_sentiment="negative",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4",
"type": "Grid",
"minColumnWidth": "14rem",
"children": [
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Revenue",
"value": "$42M",
"description": "Year to date",
"delta": "+12%"
}
]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Conversion",
"value": "3.2%",
"description": "Last 30 days",
"delta": "+0.4%"
}
]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Avg. Order",
"value": "$128",
"description": "Per transaction",
"delta": "-$3",
"trend": "down",
"trendSentiment": "negative"
}
]
}
]
}
]
}
}
```
## 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.
```python Python expandable icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Card, CardContent, CardHeader, CardTitle, Column, Grid, Metric
from prefab_ui.components.charts import BarChart, ChartSeries
data = [
{"month": "Jan", "revenue": 186000},
{"month": "Feb", "revenue": 305000},
{"month": "Mar", "revenue": 237000},
{"month": "Apr", "revenue": 273000},
{"month": "May", "revenue": 209000},
{"month": "Jun", "revenue": 314000},
]
with Column(gap=4):
with Grid(min_column_width="14rem", gap=4):
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Revenue",
value="$1.52M",
description="Q2 2025 total",
delta="+12%",
)
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Active Users",
value="26,104",
description="Monthly active",
delta="+4.3%",
)
with Card():
with CardContent(css_class="p-6"):
Metric(
label="Infra Costs",
value="$48K",
description="vs. last month",
delta="-15%",
trend="down",
trend_sentiment="positive",
)
with Card():
with CardHeader():
CardTitle("Monthly Revenue")
with CardContent():
BarChart(
data=data,
series=[ChartSeries(data_key="revenue", label="Revenue")],
x_axis="month",
height=280,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4",
"type": "Column",
"children": [
{
"cssClass": "gap-4",
"type": "Grid",
"minColumnWidth": "14rem",
"children": [
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Revenue",
"value": "$1.52M",
"description": "Q2 2025 total",
"delta": "+12%"
}
]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Active Users",
"value": "26,104",
"description": "Monthly active",
"delta": "+4.3%"
}
]
}
]
},
{
"type": "Card",
"children": [
{
"cssClass": "p-6",
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Infra Costs",
"value": "$48K",
"description": "vs. last month",
"delta": "-15%",
"trend": "down",
"trendSentiment": "positive"
}
]
}
]
}
]
},
{
"type": "Card",
"children": [
{
"type": "CardHeader",
"children": [{"type": "CardTitle", "content": "Monthly Revenue"}]
},
{
"type": "CardContent",
"children": [
{
"type": "BarChart",
"data": [
{"month": "Jan", "revenue": 186000},
{"month": "Feb", "revenue": 305000},
{"month": "Mar", "revenue": 237000},
{"month": "Apr", "revenue": 273000},
{"month": "May", "revenue": 209000},
{"month": "Jun", "revenue": 314000}
],
"series": [{"dataKey": "revenue", "label": "Revenue"}],
"xAxis": "month",
"height": 280,
"stacked": false,
"horizontal": false,
"barRadius": 4,
"showLegend": true,
"showTooltip": true,
"animate": true,
"showGrid": true,
"showYAxis": true,
"valueFormat": "auto"
}
]
}
]
}
]
}
}
```
## With Sparklines
Place a [Sparkline](/docs/components/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.
```python Python expandable icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Card, CardContent, Grid
from prefab_ui.components.charts import Sparkline
from prefab_ui.components import Metric
with Grid(min_column_width="14rem", gap=4):
with Card(css_class="pb-0 gap-0"):
with CardContent():
Metric(label="Revenue", value="$1.52M", delta="+12%")
Sparkline(
data=[120, 132, 101, 134, 90, 230, 210, 182, 191, 234, 290, 330],
variant="success", fill=True, css_class="h-16",
)
with Card(css_class="pb-0 gap-0"):
with CardContent():
Metric(
label="Response Time", value="284ms",
delta="+18ms", trend="up", trend_sentiment="negative",
)
Sparkline(
data=[180, 200, 220, 205, 240, 260, 250, 275, 290, 284],
variant="destructive", fill=True, css_class="h-16",
)
with Card(css_class="pb-0 gap-0"):
with CardContent():
Metric(label="Active Users", value="26,104", delta="+4.3%")
Sparkline(
data=[22, 23, 21, 24, 23, 25, 24, 26, 25, 26],
variant="info", fill=True, css_class="h-16",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4",
"type": "Grid",
"minColumnWidth": "14rem",
"children": [
{
"cssClass": "pb-0 gap-0",
"type": "Card",
"children": [
{
"type": "CardContent",
"children": [{"type": "Metric", "label": "Revenue", "value": "$1.52M", "delta": "+12%"}]
},
{
"cssClass": "h-16",
"type": "Sparkline",
"data": [120, 132, 101, 134, 90, 230, 210, 182, 191, 234, 290, 330],
"variant": "success",
"fill": true,
"curve": "linear",
"strokeWidth": 1.5
}
]
},
{
"cssClass": "pb-0 gap-0",
"type": "Card",
"children": [
{
"type": "CardContent",
"children": [
{
"type": "Metric",
"label": "Response Time",
"value": "284ms",
"delta": "+18ms",
"trend": "up",
"trendSentiment": "negative"
}
]
},
{
"cssClass": "h-16",
"type": "Sparkline",
"data": [180, 200, 220, 205, 240, 260, 250, 275, 290, 284],
"variant": "destructive",
"fill": true,
"curve": "linear",
"strokeWidth": 1.5
}
]
},
{
"cssClass": "pb-0 gap-0",
"type": "Card",
"children": [
{
"type": "CardContent",
"children": [
{"type": "Metric", "label": "Active Users", "value": "26,104", "delta": "+4.3%"}
]
},
{
"cssClass": "h-16",
"type": "Sparkline",
"data": [22, 23, 21, 24, 23, 25, 24, 26, 25, 26],
"variant": "info",
"fill": true,
"curve": "linear",
"strokeWidth": 1.5
}
]
}
]
}
}
```
## API Reference
The metric name displayed above the value (e.g. `"Revenue"`, `"Active Users"`).
The headline number. Strings are displayed as-is, so pre-format with currency symbols, commas, or units as needed.
Optional text below the value for additional context like time ranges or data sources.
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.
Arrow direction: `"up"`, `"down"`, or `"neutral"`. Inferred from `delta` when omitted -- positive deltas point up, negative point down.
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).
Additional Tailwind CSS classes.
## Protocol Reference
```json Metric theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Metric",
"id?": "string",
"onMount?": "any",
"label": "string (required)",
"value": "number | string (required)",
"description?": "string",
"delta?": "number | string",
"trend?": "up | down | neutral",
"trendSentiment?": "positive | negative | neutral",
"cssClass?": "string"
}
```
For the complete protocol schema, see [Metric](/docs/protocol/metric).