Chapter 03·Common UI Defects·~8 min·
Number, Currency, Date, and Unit Formatting
The ECMAScript Intl APIs format numbers, currencies, dates, and units from CLDR locale tables. The value 1234567.89 formats as 1,234,567.89 in en-US, 1.234.567,89 in de-DE, 1'234'567.89 in de-CH, and 12,34,567.89 in en-IN.
Overview
Every locale defines specific rules for decimal separators, digit grouping, currency placement, and date order. Hardcoding string templates locks an interface to one region. The ECMAScript `Intl` APIs format values directly from CLDR locale data.
Core rule
Format numbers, currencies, dates, and units with ECMAScript Intl APIs and CLDR locale data. Never construct formatted strings by manual concatenation.
Specification note: In en-IN, the number 1234567.8 formats as 12,34,567.8 with two-digit groups above the thousands place. In de-CH, the group separator is an apostrophe.
Failure mode
Hardcoding $1,234.56 or 12/31/2024 applies en-US formatting rules to every user. In de-DE, the same values format as 1.234,56 $ and 31.12.2024.
Decimal precision, group separators, and digit glyphs vary by locale. Japanese yen (JPY) uses 0 decimal places, while Bahraini dinar (BHD) uses 3. German uses a comma as the decimal separator, and Egyptian Arabic (ar-EG) uses Arabic-Indic digits. Displaying 1,234 to a German user changes a thousand-unit quantity into a decimal fraction near 1.2.
Numbers, dates, times, and currencies follow regional conventions defined in CLDR. Hardcoding separators or currency symbols produces confusing and incorrect data.
Business stakes & user risk
Displaying $1,500 as 1.500 or mixing day/month date ordering (03/04/2026: March 4 or April 3?) leads to payment disputes, scheduling failures, and customer support tickets.
Rule of thumb
Never write custom string concatenation for numbers or dates. Always pass values to Intl.NumberFormat and Intl.DateTimeFormat.
The Novice Trap vs. Production Standard
Contrast the intuitive assumption with the architecture required for global releases.
“Adding a dollar sign to the front of a number and calling .toFixed(2) handles currency formatting.”
Naive approach: Hardcoded currency and decimal
const displayPrice = "$" + price.toFixed(2); // Outputs: $1500.50Defect:In Germany, standard format is '1.500,50 USD'. In France, '1 500,50 $US'. Japanese Yen with .toFixed(2) produces invalid fractions like '¥1500.00'.
Currencies place symbols before or after numbers, use periods or commas for decimals, and some currencies (such as JPY and KRW) have no decimal units.
Production standard: Intl.NumberFormat
new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(price);Benefit:Produces culturally accurate symbol placement, decimal separators, and fraction digit precision for all 200+ locales.
Cross-Functional Review Questions
Questions for product managers, designers, engineers, and testers to ask during sprint reviews.
“Are all frontend and backend date, number, and currency displays generated via Intl APIs?”
“Do our checkout and invoice screens support zero-decimal currencies like JPY and KRW?”
“Does the UI accommodate varying currency symbol lengths and positions?”
“Are date formats verified in both day-first (en-GB, de-DE) and month-first (en-US) locales?”
Mechanism
Declarative options and CLDR patterns
Intl.DateTimeFormat and Intl.NumberFormat accept a BCP 47 locale tag and a declarative options bag rather than a rigid format pattern string. The runtime looks up the target locale in CLDR to resolve field order, separator characters, numbering system, and calendar.
A single options object formats as 4/21/26, 6:30 PM in en-US and 21.04.26, 18:30 in de-DE. In ar-EG, the formatter selects Arabic-Indic digits automatically. In th-TH, it formats the Buddhist Era year 2569.
Number formatting resolves group sizes (1,234,567 in en-US vs 12,34,567 in en-IN), decimal markers, ISO 4217 currency minor units (0 for JPY, 2 for EUR, 3 for BHD), and compact powers (1.2M in English vs 123.5万 in Japanese). When custom typography requires separate styling for currency symbols or decimals, formatToParts() returns an ordered array of typed tokens.
Interactive demo
Guided exercises
- 1In the money section, switch the currency from USD to JPY while keeping the same numeric amount. The formatter removes the decimal fraction and rounds to an integer because CLDR defines 0 minor units for Japanese yen (and 3 minor units for Bahraini dinar).
- 2Set the locale to ar-EG and inspect all formatted outputs. The output uses Arabic-Indic digits (١٢٣…) and Arabic thousands and decimal separators (٬ and ٫) because `arab` is the default CLDR numbering system for `ar-EG`.
- 3Set the calendar dropdown to “Buddhist (Thai)”. The formatted year changes from 2026 to 2569, reflecting the 543-year offset of the Thai Buddhist calendar.
- 4In the four-locale hero, compare en-US and en-IN for the same numeric value. en-US groups by thousands (1,234,567), whereas en-IN groups by two-digit lakhs and crores above the thousands place (12,34,567).
- 5In the locale matrix (Date & time mode), set Date style to none, Time style to short, and then set Hour cycle to h23. At default settings, en-US renders a 12-hour clock (6:30 PM) while de-DE and ja-JP render a 24-hour clock (18:30). Setting `hourCycle: 'h23'` overrides the locale default across all rows.
- 6Switch the locale matrix to Currency mode and step Symbol display through symbol, code, and name. The formatter switches between the localized currency sign, the ISO 4217 code (JPY), and the inflected currency name (“Japanische Yen” in de-DE).
Tag passed to Intl: en-US
One amount, four locales
en-US
$1,234,567.89
US (baseline)
en-IN
$12,34,567.89
Indian grouping
de-CH
$ 1'234'567.89
Swiss apostrophe
ar-EG
١٬٢٣٤٬٥٦٧٫٨٩ US$
Arabic-Indic digits
Locale matrix · one option set, eleven locales
The options say what to show; each locale's CLDR data sets how it is written.
| Locale | Output | What moved |
|---|---|---|
| en-US | Apr 21, 2026, 6:30 PM | month first, 12-hour |
| en-GB | 21 Apr 2026, 18:30 | day first, 24-hour |
| de-DE | 21.04.2026, 18:30 | dots group, comma decimal |
| fr-FR | 21 avr. 2026, 18:30 | narrow no-break spaces |
| pt-BR | 21 de abr. de 2026, 18:30 | |
| ru-RU | 21 апр. 2026 г., 18:30 | |
| hi-IN | 21 अप्रैल 2026, 6:30 pm | lakh/crore grouping |
| th-TH | 21 เม.ย. 2569 18:30 | Buddhist calendar by default |
| ja-JP | 2026/04/21 18:30 | year first |
| zh-CN | 2026年4月21日 18:30 | year first |
| ar-EG | ٢١/٠٤/٢٠٢٦، ٦:٣٠ م | Arabic-Indic digits, RTL |
Same instant in every row, in UTC. th-TH prints the Buddhist-era year, 543 ahead of the Gregorian (2569 for 2026), because Buddhist is its default calendar.
Numbers & currency
| Style | Output | Code |
|---|---|---|
| Decimal | 1,234,567.89 | NumberFormat() |
| Currency | $1,234,567.89 | NumberFormat({ style: 'currency', currency: 'USD' }) |
| Compact | 1.2M | NumberFormat({ notation: 'compact', maximumFractionDigits: 1 }) |
| Percent (0.7321) | 73.21% | NumberFormat({ style: 'percent' }) |
Minor units (ISO 4217)
Most currencies have 2 decimal places; JPY, KRW, VND, and CLP have 0, and BHD, KWD, OMR, and JOD have 3. Payment code that converts to minor units by multiplying by 100 charges 100× too much in JPY and 10× too little in BHD.
new Intl.NumberFormat(locale, {style:'currency',currency}).resolvedOptions().minimumFractionDigits returns the digit count for any currency.
Units
| Style | Output | Code |
|---|---|---|
| Unit (long) | 42.5 kilometers | NumberFormat({ style: 'unit', unitDisplay: 'long' }) |
| Unit (narrow) | 42.5km | NumberFormat({ style: 'unit', unitDisplay: 'narrow' }) |
Dates & times
| Style | Output | Code |
|---|---|---|
| short | 4/21/26 | { dateStyle: 'short' } |
| medium | Apr 21, 2026 | { dateStyle: 'medium' } |
| long | April 21, 2026 | { dateStyle: 'long' } |
| full + time | Tuesday, April 21, 2026 at 6:30:00 PM UTC | { dateStyle: 'full', timeStyle: 'long' } |
Relative time
| Style | Output | Code |
|---|---|---|
| auto | 3 days ago | RelativeTimeFormat({ numeric: 'auto' }) |
List formatting
| Style | Output | Code |
|---|---|---|
| Conjunction | apples, oranges, and pears | ListFormat({ type: 'conjunction' }) |
| Disjunction | apples, oranges, or pears | ListFormat({ type: 'disjunction' }) |
Display names
| Style | Output | Code |
|---|---|---|
| Country 'DE' | Germany | DisplayNames({ type: 'region' }) |
| Language 'zh-Hant' | Traditional Chinese | DisplayNames({ type: 'language' }) |
| Currency 'JPY' | Japanese Yen | DisplayNames({ type: 'currency' }) |
Segmenter (graphemes & words)
Input
"👩👩👧👦 こんにちは"
Graphemes (7)
Words from "Hello, 世界! How are 你?"
ICU segments the Chinese with a dictionary: 世界 is one word.
The same amount, formatted for every supported locale
First day of the week & weekend
The first day of the week and the weekend days are locale data (Intl.Locale.weekInfo). A calendar grid hardcoded to a Sunday start and a Saturday–Sunday weekend is wrong in Germany (Monday start) and Saudi Arabia (Friday–Saturday weekend).
The week starts on Sun. The weekend is Sat + Sun. (The US starts Sunday, most of Europe Monday, much of the Middle East Saturday.)
Measurement systems
Intl formats the unit it is given. It does not convert values or choose a measurement system; application code maps the locale to a system, converts, then formats.
The current locale en-US maps to US customary.
Implementation rules
- Use built-in
Intlformatters. CallIntl.NumberFormat,Intl.DateTimeFormat, andIntl.RelativeTimeFormatwith the negotiated user locale. These APIs apply CLDR grouping sizes, currency minor units, numbering systems, and date field ordering. - Pass ISO 4217 currency codes to
Intl.NumberFormat. Configure{ style: "currency", currency: "JPY" }and let CLDR set the decimal precision and symbol placement. Do not call.toFixed(2)or concatenate currency symbols. - Use
formatToParts()for custom typography. When a design styles currency symbols or decimal fractions separately, iterate over the token array fromformatToParts(). Never split formatted strings with regular expressions. - Format relative times with
Intl.RelativeTimeFormat. Replace manual timestamp arithmetic and hardcoded English labels with locale-aware relative time formatting.
Operational context
Roles
Workflow stages
- ·Building checkout, billing, or analytics views
- ·Supporting multiple currencies and numbering systems
- ·Component library API design
Use the tool: CLDR explorer · any value in every locale you ship →
Production incident
CLDR specifies `U+202F` (Narrow No-Break Space) as the thousands group separator in French (`1 234,56`). Unit tests that assert against a standard ASCII space (`U+0020`) fail even when the visual output is identical.