Data
BigNumber
One number, at the size of a headline.
Usage
When to reach for it
Ships from@misoto22/design/charts
import { BigNumber } from '@misoto22/design/charts'Notes
One number, at the size of a headline.
The form most dashboards need most often and most chart libraries do not ship, on the grounds that it is not a chart. It is the right answer whenever there is exactly one figure to report: a plot of a single value is a plot whose shape carries nothing, and the reader has to decode an axis to recover a number that could simply have been printed.
The delta is where this earns its place over a <p>. Direction is stated by the CALL SITE (intent), never inferred: "errors down 12%" is good news and "revenue down 12%" is not, and no component can tell which it is holding. Where the direction is known, the arrow and the word carry it — the status colour is the third signal, never the only one.
Anatomy
| Element | Description |
|---|---|
| Labelrequired | What the number counts, as an eyebrow at --ink-3-aa above it. Nothing binds it to the value programmatically — no aria-labelledby, no role — so document order is the whole association. |
| Valuerequired | The number itself, in the editorial face at --fs-lead with tabular figures. Rendered exactly as handed over: no unit, currency or locale is guessed on its behalf. |
| Delta | The line under the number, from delta: the change through format — a signed percentage unless replaced — and delta.label at --ink-3-aa saying what it is a change from. |
| Direction mark | Inside the delta: an aria-hidden arrow, up, down or flat at zero, and the status tint, --ok or --danger, or --ink-2 while nothing has been judged. Two carriers, so the reading survives greyscale and forced colours. |
| Verdict | The sr-only words beside the arrow — up or down, then better or worse once intent has been set. It is what a screen reader gets in place of the tint. |
| Note slot | children, under the number with a margin: where a Sparkline, a denominator or a caveat goes. |
Best practices
Do
- Give the figure something to be judged against. On its own a number cannot be read — 48,210 is neither good nor bad until it is beside last month — and this component carries exactly two places for that: delta for one comparison, children for the Sparkline or the denominator under it.
- Pass delta.value as a ratio. The default formatter multiplies by a hundred and prefixes the sign, so 0.124 prints as +12.4% and 12.4 prints as +1240%. A change already expressed in points needs its own format handed over with it.
- Set intent on any delta meant to be coloured. It defaults to neutral, which renders the change at --ink-2 and says only which way it moved — correct for a figure nobody has judged, and rarely what the author of a revenue card thought they had written.
- Let value be null when there is no reading. It prints an em dash at --ink-3-aa with an sr-only “No data” behind it, which is a number nobody has; a blank line under a label is a broken layout as far as the reader can tell. emptyValue changes what the dash is.
Don’t
- Do not expect a delta of exactly zero to carry the intent’s verdict. There is no direction for an intent to judge, so the tone, the arrow and the announced words all say “no change” and stop — a zero under up-is-good used to be announced as “no change, worse” while the page showed no judgement at all.
- Do not separate the label from the number. The value is text in a span rather than a labelled element, and the label is a sibling read before it, so a layout that moves the figure into its own column — or reuses one label over two figures — hands a screen reader a bare number with nothing naming it.
Examples
default
Three deltas, each with its direction stated by the call site rather than inferred from the sign: errors down 12 percent is good news and revenue down 12 percent is not, and no component can tell which one it is holding, so intent is what decides whether a change is tinted ok or danger. The arrow and the screen-reader word carry that same reading, which is what keeps it legible in greyscale, under forced colours, and to a reader who cannot separate the two tints. A delta of zero is flat — a sideways arrow and no tint at all — which is why a neutral intent still has something to say.
with sparkline
The pairing every dashboard reaches for: the number answers how much, and the run beneath it answers how it got there, without spending a whole panel on an axis nobody reads off. children is where that run goes, under the label, the number and the delta; the sparkline takes a label of its own because the heading above it names a different fact. Reach for a LineChart the moment the shape has to be read precisely — a sparkline has no axis to read it against, by design.
points and a missing value
Two things this component refuses to guess. The default delta format is a signed percentage, so 0.6 would print as plus 60 percent — right for a ratio and wrong for a rate that is already a percentage, where the change is 0.6 percentage points; format is how a call site says which of the two it is holding. The second card has no figure yet and no delta at all: value takes a node rather than a number precisely so the call site can print an em dash there, because a zero would be a claim and a change against nothing has no direction to point in.
Types
export type DeltaIntent = 'up-is-good' | 'down-is-good' | 'neutral'Accessibility
- The delta’s direction is stated by the call site through intent, never inferred from the sign: “errors down 12%” is good news and “revenue down 12%” is not, and no component can tell which it is holding.
- The arrow and the words carry the direction; the status tint is the third signal, never the only one — so the reading survives greyscale, forced colours and colour blindness.
- value is taken already formatted. The component does not guess a unit, a currency or a locale.