Delta
StableHow a figure moved: an arrow and a signed percentage on a tinted pill, with an optional comparison after it. It sits beside a figure and answers the merchant's next question: better or worse than before?
States
One arrow, turned to its heading: up and to the right when rising, down and to the right when falling, level when steady. A change under 0.5% either way is steady (noise, not news), so it stays neutral even though it keeps its sign. The pill is green when the change is good news and red when it is bad.
Watch it change
When the direction changes, the arrow swings to its new heading on a spring and the pill changes colour, so the change itself is visible. Press Next day.
When up is bad
Most figures are good when they rise: takings, orders, conversion. For the ones where a rise is bad news (refunds, returns, abandoned checkouts), set positiveIsGood={false}. The arrow still shows the direction; only the colour flips.
Beside a figure
A delta always belongs to a figure. The figure stays in ink, set in Sora with tabular numerals, and the delta carries the colour on its own pill. label says what the change is measured against, in quiet text after the pill. Headline figures sit on one hairline, not in boxes: the real strip, with a chart beneath it, is Figure tabs.
Sizes
md (22px, 12px text) is the default, beside figures. sm (18px, 11px text) is for tables and dense rows.
Precision
One decimal place by default. Use precision={0} for large swings, where a decimal adds nothing, and 2 only where small differences really matter, such as a conversion rate.
In both themes
Every state and both sizes, light and dark side by side.
formatDelta
The formatter the pill uses, exported for text, tooltips and exports that need the same wording: a plus for a rise, a true minus sign for a fall, UK number formatting, and no sign at all when the change rounds to nothing. precision is rounded and held between 0 and 4.
| Call | Returns |
|---|---|
formatDelta(18.2) | '+18.2%' |
formatDelta(-4) | '−4.0%' |
formatDelta(0.04) | '0.0%' |
formatDelta(6.254, 2) | '+6.25%' |
formatDelta(1204.56, 0) | '+1,205%' |
Guidelines
- Always say what the change is against: "vs yesterday", "vs last Tuesday", "vs this time last week".
- Compare like with like: the same span of time, and the same point in the day for today.
- One delta per figure. Two comparisons on one figure belong in a chart or a tooltip.
Accessibility
- The value carries the direction in text: a plus for a rise, a true minus sign for a fall, which screen readers read as minus. The arrow is hidden.
- Whether the change is good is shown by colour alone. Where it matters, say it in words nearby, for example in the label ("refunds vs last month") or a summary line.
- The comparison label is read straight after the value.
- Under reduced motion the arrow turns to its new heading at once instead of swinging; the colour change stays.
Props
Also accepts every native span attribute except children.
Delta
| Prop | Type | Default | Description |
|---|---|---|---|
valueRequired | number | None | Percentage change: 18.2 for +18.2%. Anything that is not a finite number reads as 0. |
positiveIsGood | boolean | true | Whether a rise is good news. Set false for refunds, returns and abandoned checkouts. |
precision | number | 1 | Decimal places, 0 to 4. |
label | ReactNode | None | The comparison after the pill, e.g. "vs yesterday". |
size | 'sm' | 'md' | 'md' | 18px for tables and dense rows, 22px beside figures. |
formatDelta(value, precision)
| Prop | Type | Default | Description |
|---|---|---|---|
valueRequired | number | None | Percentage change. |
precision | number | 1 | Decimal places, rounded and held between 0 and 4. |