Loading…

Metric Delta

A headline number with a change indicator that knows which direction is good.

Data
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add metric-delta

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { MetricDelta } from "@/components/ui/metric-delta";

Examples

Every example the tests run, live and operable, side by side.

Default
Polarity Matters
Zero Baseline
Below The Noise Floor
No Comparison
Unchanged
Dashboard Row
Ai Evaluation

API

Generated from the component's own types, so a prop cannot appear here without existing.

<MetricDelta>

Prop	Type	Default
`label` (required) Names the metric.	`string`	—
`value` (required) The current value.	`number`	—
`comparisonLabel` What the previous value represents, e.g. "vs last week".	`string`	`"vs previous period"`
`format` Formats the headline value.	`(value: number) => string`	`defaultFormat`
`insignificantBelow` Relative change below which the delta is shown without sentiment, as a fraction. Presentation only — this is not a significance test.	`number`	`0`
`polarity` Whether a rise is good news. Churn, latency, error rate and cost are all `lower-is-better`, and getting this wrong paints bad news green.	`MetricPolarity`	`"higher-is-better"`
`previous` The value being compared against. Omit when there is nothing to compare.	`number`	—
`sampleSize` Included in the accessible description when given, so a reader can judge the change for themselves. Never used to compute significance.	`number`	—
`sentiment`	`"good" \| "bad" \| "neutral"`	`"neutral"`

Plus every attribute of <div> except children.

Accessibility

The meaning is never carried by colour and an arrow alone, which fails WCAG 1.4.1 — the direction and the comparison are always stated in text. The tile reads as one sentence rather than three fragments: the visible number and delta are aria-hidden and a single screen-reader description carries value, direction, comparison and, where given, sample size. A zero baseline is announced as having no percentage rather than as an infinite one.

Quality

Measured from the source and its tests at build time.

All scores

7/7

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — does not apply
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Used in

Whole screens assembled from this component. Installing one brings this and everything else it needs with it.

Prop

Type

Default

label

Names the metric.

string

—

value

The current value.

number

—

comparisonLabel

What the previous value represents, e.g. "vs last week".

string

"vs previous period"

format

Formats the headline value.

(value: number) => string

defaultFormat

insignificantBelow

Relative change below which the delta is shown without sentiment, as a fraction. Presentation only — this is not a significance test.

number

0

polarity

Whether a rise is good news. Churn, latency, error rate and cost are all lower-is-better, and getting this wrong paints bad news green.

MetricPolarity

"higher-is-better"

previous

The value being compared against. Omit when there is nothing to compare.

number

—

sampleSize

Included in the accessible description when given, so a reader can judge the change for themselves. Never used to compute significance.

number

—

sentiment

"good" | "bad" | "neutral"

"neutral"