Metric
React KPI metric card with label, value, change delta, trend, an optional sparkline, icon, and action slots. Group tiles with MetricGroup for dashboards.
Metric shows a stat from slots: icon, label, value, change with trend, and an optional MetricChart sparkline. Arrange cards with MetricGroup.
When to use
Use Metric for the headline numbers of a dashboard: requests this month, average processing time, satisfaction score. Show the change against a period so numbers have context. Arrange several with MetricGroup.
For a full series, use Charts instead of a sparkline.
Examples
Props
Props declared by Metric. Native attributes of the underlying element pass through.
<Metric>
| Prop | Type | Default | Description |
|---|---|---|---|
layout | "small" | "large" | ||
icon | react.ReactNode | Featured icon, shown in a 32px brand-tinted circle at the start of the header. | |
label | react.ReactNode | Short label beside the icon (e.g. "24h Views"). | |
action | react.ReactNode | Header slot at the inline-end (e.g. a "more" menu trigger button). | |
value | react.ReactNode | The metric, pre-formatted by the consumer (e.g. "50%", "SAR 1.2M"). | |
change | react.ReactNode | Change text - include the sign (e.g. "+100%") so AT conveys direction; color comes from trend. | |
trend | Trend | Trend: up → success arrow, down → error arrow. Drives the glyph + color. | |
changeType | ChangeType | Change glyph style - 01 directional arrow (default) · 02 trend glyph. | |
changeLabel | react.ReactNode | Muted comparison text beside the change (e.g. "vs last month"). | |
chart | react.ReactNode | Trend chart - pass a <MetricChart> (full-width in large, beside the value in small). | |
footer | react.ReactNode | Footer actions; when present, a full-bleed divider sits above a space-between actions row. |
<MetricChange>
| Prop | Type | Default | Description |
|---|---|---|---|
trend | Trend | ||
type | ChangeType | 01 directional arrow (default) · 02 trend glyph. |
<MetricChart>
| Prop | Type | Default | Description |
|---|---|---|---|
datarequired | number[] | The series to plot (any numeric scale). | |
trend | Trend | Line + area + marker color: up → success, down → error. Default up. | |
markers | number[] | Indices of data to mark with a dot. Defaults to the highest point. |
<MetricGroup>
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | ||
gap | "sm" | "md" | "lg" | ||
columns | number | Fixed column count for the horizontal grid (collapses to one column on narrow screens). Omit for an auto-fit responsive grid. |
Accessibility
The label and value are text, so they read in order. The trend icon is decorative; the change text must include the direction, such as "+12%", so it is not conveyed by color or icon alone.
The sparkline is hidden from assistive technology and the value carries the meaning. Separators between tiles use role="separator".