/// Data Display
MoneyAmount
A deterministic currency renderer — mono tabular figures, minor-unit aware, compact and sign-colored.
import { MoneyAmount } from "@protocore/pds";Basics
Pass a major-unit amount and an ISO 4217 currency. Formatting goes through Intl.NumberFormat with a fixed locale (default "en") so server and client renders match byte-for-byte.
Minor units & compact
When money arrives off the wire as integer minor units (cents), set minorUnits={2} and the value is divided by 100 before formatting. compact switches to short notation (2400000 → $2.4M).
Sign policy
sign controls the leading sign: "auto" shows − on negatives only, "always" prefixes + on positives (and tones them success), "never" hides it. Negatives always tone danger. The minus is a typographic −, not an ASCII hyphen.
| credit (always) | +€1,250.00 |
| debit (auto) | −€840.75 |
| balance (never) | €840.75 |
When to use it
MoneyAmount is the single renderer for any currency figure — balances, fees, invoice totals, ledger lines. Tabular mono figures keep columns aligned, and passing minorUnits avoids float rounding on wire values. Because the locale is explicit, it is safe in server components with no hydration drift.
Use MetricDelta for a *change* in a metric (+4.2%) rather than an absolute amount. For an arbitrary number that isn't money, format it yourself — MoneyAmount always renders a currency symbol. A non-finite or unrecognized value renders an honest literal (the raw input plus the code), never a fabricated figure.
Usage
Do
- Pass integer minor units with `minorUnits` when that's what the API returns.
- Keep one explicit `locale` across a view so grouping/decimals are consistent.
- Use `sign="always"` for ledgers where credit/debit direction must read at a glance.
- Use `compact` for dashboards and headline figures, not for exact line items.
Don't
- Don't pre-divide cents yourself and also pass `minorUnits` — pick one.
- Don't use it for non-currency numbers; it always emits a currency symbol.
- Don't rely on color alone to convey sign — the glyph carries it too.
- Don't feed it already-formatted strings with symbols; pass the raw number or numeric string.
Accessibility
- Renders a plain `<span>` of formatted text; the number is read as written, symbol included.
- Sign tone (danger on negatives, success on `always` positives) is reinforced by the leading sign glyph, so it never depends on color alone.
- Invalid input surfaces a `title` explaining the unrecognized value/currency and renders the literal rather than a fake amount.
MoneyAmount props
| Prop | Type | Default | Description |
|---|---|---|---|
amount * | string | number | — | The value to render. A `number`, or a numeric `string` off the wire. When `minorUnits` is set this is interpreted as integer minor units (e.g. cents); otherwise it is the major-unit amount as-is. |
className | string | — | |
compact | boolean | false | Use compact notation (`1200000` → `1.2M`). |
currency * | string | — | ISO 4217 currency code (e.g. `"EUR"`, `"USD"`, `"JPY"`). |
locale | string | en | BCP-47 locale used for grouping / decimal separators. Fixed and explicit so SSR and hydration agree. |
minorUnits | number | — | Number of fractional (minor-unit) digits `amount` is expressed in — e.g. `2` means `amount` is cents and is divided by 100 before formatting. Omit when `amount` is already a major-unit value. |
sign | enum | auto | Sign policy: `"auto"` shows `−` on negatives only, `"always"` prefixes `+` on positives too, `"never"` hides the sign entirely. |
style | CSSProperties | — |