# MetricDelta
- **Category:** Data Display (`data-display`)
- **Slug:** `data-display/metric-delta`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { MetricDelta } from "@protocore/pds";`
- **Docs:** https://pds.protocore.io/components/data-display/metric-delta
> A compact directional change indicator — a ▲▼ glyph plus a signed magnitude, toned by direction.
## When to use it
**MetricDelta** annotates a metric with its *change* — the `+4.2%` next to a KPI, the trend on a stat tile, the movement in a dashboard cell. It encodes direction three ways (glyph, sign, tone) so it never depends on color alone.
Use **MoneyAmount** for an absolute currency figure rather than a delta. For a live-vs-baseline status indicator that isn't numeric, use **StatusDot**. Remember `invertColor` for "lower is better" metrics — otherwise a latency improvement will misleadingly tone danger.
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string` | no | — | — |
| `format` | `enum` | no | `percent` | Format the magnitude as a percentage (appends `%`) or a plain number. |
| `invertColor` | `boolean` | no | `false` | Invert the color mapping for metrics where a decrease is good (e.g. latency, error rate) — down becomes success, up becomes danger. |
| `style` | `CSSProperties` | no | — | — |
| `value` | `number` | yes | — | The signed change. Positive is "up", negative is "down", zero is "flat". |
## Examples
### Basics
Pass a signed `value`: positive reads "up" (success, ▲), negative "down" (danger, ▼), zero "flat" (neutral, —). The magnitude formats as a percentage by default with an explicit sign.
```tsx
import { MetricDelta } from "@protocore/pds";
export default function MetricDeltaBasics() {
return (
);
}
```
### Number format & inverted color
Use `format="number"` for a plain count instead of a percentage. Set `invertColor` for metrics where a decrease is good — latency, error rate — so a drop tones success and a rise tones danger.
```tsx
import { MetricDelta } from "@protocore/pds";
export default function MetricDeltaInverted() {
return (
| Throughput |
|
{/* lower latency is good — invert so a drop reads as success */}
| p99 latency |
|
| Failed deliveries |
|
);
}
```
## Usage
**Do**
- Use it beside a metric to show how it moved, not its absolute value.
- Set `invertColor` for latency, error rate, cost — anywhere down is good.
- Use `format="number"` for count deltas (e.g. +3 failed jobs).
- Let a zero value read as neutral "flat" rather than forcing a direction.
**Don't**
- Don't use it for a standalone number with no baseline — that's not a delta.
- Don't hardcode a `+`/`−` in the value; the component derives the sign.
- Don't forget `invertColor` on "lower is better" metrics — the color will lie.
- Don't rely on tone alone; keep it near a label that names the metric.
## Accessibility
**Notes**
- The direction glyph (▲▼—) is `aria-hidden`; direction is still conveyed by the signed magnitude text.
- Tone is a data attribute driving color; the sign and glyph make direction legible without color perception.
- Renders a plain `` — pair it with a visible metric label so screen-reader users get context.
## Related
`money-amount`, `relative-time`, `status-dot`, `code-ref`
---
© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/