Skip to content
Documentation

ADR-013: Locale & Number Formatting

Decision

All user-facing numbers, currency, and percentages are rendered through locale-aware utility helpers (en-US, USD) at the display layer. Raw toFixed(), inline .toLocaleString(), and manual number formatting are forbidden.

Key rules

  • Use the canonical helpers for every user-facing value: formatCurrency(value), formatNumber(value), formatPercent(value).
  • Never use raw toFixed(), inline .toLocaleString(), or hand-rolled number formatting.
  • Never interpolate numbers directly into JSX (no ${value}, no {amount}%).
  • Locale is en-US; currency is USD. Pass overrides only when a value genuinely needs them.
  • Format at the display layer only — data structures, state, and API payloads stay numeric.

Code patterns

formatCurrency(1450.79)    // → "$1,450.79"
formatCurrency(12000)      // → "$12,000.00"
formatNumber(12000)        // → "12,000"
formatNumber(3.14159, 2)   // → "3.14"
formatPercent(34.5)        // → "34.50%"
formatPercent(100, 0)      // → "100%"
function formatCurrency(amount: number): string {
  return amount.toLocaleString('en-US', {
    style: 'currency', currency: 'USD',
    minimumFractionDigits: 2, maximumFractionDigits: 2,
  });
}


function formatNumber(value: number, fractionDigits = 0): string {
  return value.toLocaleString('en-US', {
    minimumFractionDigits: fractionDigits,
    maximumFractionDigits: fractionDigits,
  });
}


function formatPercent(value: number, fractionDigits = 2): string {
  return `${formatNumber(value, fractionDigits)}%`;
}

Why

Centralizing formatting in helpers keeps thousands separators, currency symbols, and fraction digits consistent across every surface and makes the locale a single point of change. Keeping data numeric until render avoids re-parsing formatted strings and keeps arithmetic correct. The helpers wrap the ECMA-402 toLocaleString API rather than reimplementing it. The .toLocaleString() ban is on inline call-site use only — the canonical helpers are the one sanctioned wrapper around it.

Applies when

You are displaying any dollar amount, count, percentage, ratio, or other number in a component or document.

  • ADR-031 — Virginia child support rounding conventions (rounds to nearest dollar per Va. Code § 20-108.2).