TrendDelta

An inline signed-delta chip — directional glyph plus magnitude — for "vs. previous period" readouts next to any metric.

Import

import { TrendDelta } from "@roger-emerson/ploxum-primitives";

Usage

<div className="flex items-center gap-4">
  <span className="font-mono tabular-nums">14,205</span>
  <TrendDelta value={4.2} />                            {/* +4.2% — up, good */}
  <TrendDelta invertPolarity value={-1.8} />            {/* -1.8% — down, good (wait time) */}
  <TrendDelta format="number" unit="ms" value={32} />   {/* +32ms */}
  <TrendDelta size="sm" value={0} />                    {/* flat, neutral */}
</div>

Props

Prop	Type	Default	Description
`value`	`number`	—	Signed delta vs. previous period. Required.
`format`	`"percent" \| "number"`	`"percent"`	Percent appends a `%` suffix; number appends the `unit`, if any.
`precision`	`number`	`1`	Decimal places.
`unit`	`string`	—	Unit suffix for `number` format (ignored for `percent`).
`direction`	`"up" \| "down" \| "flat"`	derived from sign	Override the derived direction.
`invertPolarity`	`boolean`	`false`	Flip the color mapping for down-is-good metrics (wait time, error rate).
`size`	`"sm" \| "md"`	`"md"`	11px / 13px text with matching glyph size.
`className`	`string`	—	Merged onto the root `<span>`.
`ref`	`Ref<HTMLSpanElement>`	—	Ref to the root `<span>`.

Also accepts all HTMLAttributes<HTMLSpanElement> except children. The root carries role="img" with a composed aria-label (e.g. "up 4.2 percent").

Design rules

Direction reads by glyph shape — triangle up, triangle down, flat bar — plus color. Never strip the glyph and rely on hue alone.
Use invertPolarity for down-is-good metrics instead of remapping colors manually; the glyph keeps pointing at the true direction.
Tabular numerals are baked into the chip. Don't override the font — adjacent deltas must align column-wise.
Magnitudes below 1e-6 render as flat/neutral with no sign; don't special-case zero upstream.

Storybook

Open TrendDelta in Storybook ↗