#Intl Energy Units ?

#Proposal: Add Energy & Power Units (W, kW, kWh) to ECMA-402

#Status

Stage: 0 (seeking champion)

Champion: TBD

Author: Johan Røed (@johanrd)

#Motivation

Electric vehicles, construction equipment, and building systems report energy consumption in their APIs. An increasing number of web applications are being developed to support the electrification of transport, industry, and the built environment.

It would be helpful if ECMAScript could make developing these applications easier by providing watt, kilowatt and kilowatt-hour as supported units in Intl.NumberFormat.

Currently, developers must manually format these units.

Related issue: https://github.com/tc39/ecma402/issues/739

#Use Cases

#1. Energy consumption (kWh)

Electricity billing & utility dashboards Smart home monitoring, meter readings
EV charging sessions & battery state Charging apps, fleet management, trip planning Smartcar API, rFMS vehicle data spec
Solar generation & feed-in Daily/monthly production, grid export

#2. Power ratings (W, kW)

EV charging stations Charging networks, station maps, session details
Solar & HVAC systems Panel output, inverter dashboards, heating/cooling
Real-time device power draw Smart plugs, energy meters Appliance ratings, LED lighting, home electronics

#3. Compound units

• Energy labelling — kilowatt-hour-per-year (EU energy labels)
• Carbon accounting — gram-per-kilowatt-hour (CO₂e g/kWh)
• EV efficiency — kilowatt-hour-per-kilometer, kilowatt-hour-per-mile (CLDR also defines kilowatt-hour-per-100-kilometer as a unit identifier)
• Energy density — kilowatt-hour-per-liter (battery specs)
• Energy intensity — kilowatt-hour-per-kilogram (industrial production)

#Proposed Solution

Add three sanctioned single unit identifiers to ECMA-402 §6.6.2 (IsSanctionedSingleUnitIdentifier), Table 2:

These three units cover the vast majority of consumer-facing energy applications. ECMA-402 draws from CLDR; these identifiers are already defined and localized.

AvailableCanonicalUnits() must include the three new identifiers in its return set.

#API Examples

#Narrow width, US locale:

new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour', unitDisplay: 'narrow' }).format(1234.5)
// "1,234.5 kWh"

#Short width, French locale:

new Intl.NumberFormat('fr-FR', { style: 'unit', unit: 'kilowatt-hour', unitDisplay: 'short' }).format(1234.5)
// "1 234,5 kWh"

#Long width, German locale:

new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'watt', unitDisplay: 'long' }).format(1200)
// "1.200 Watt"

#Power ratings across locales:

new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt' }).format(5.2)  // "5.2 kW"
new Intl.NumberFormat('fr-FR', { style: 'unit', unit: 'kilowatt' }).format(5.2)  // "5,2 kW"

#Compound units (once base units are sanctioned):

new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour-per-mile', unitDisplay: 'narrow' }).format(0.29)
// "0.29 kWh/mi"

#Today (before this proposal), these throw RangeError:

new Intl.NumberFormat('en-US', { style: 'unit', unit: 'kilowatt-hour' }).format(42.5)
// RangeError: Invalid unit argument for option unit: kilowatt-hour

#Technical Considerations

• CLDR support: All proposed units are already defined in Unicode CLDR with complete localization across all supported locales (unit.xml)
• No breaking changes: Purely additive
• Minimal payload impact: Data already exists in CLDR, three units represent a minimal addition.
• Consistent with existing patterns: Follows same conventions as kilogram/kilometer, fluid-ounce
• Userland workarounds and bugs: Without native support, developers use libraries like convert-units (~150K weekly npm downloads), or build custom formatting logic leading to locale bugs (de-CH kWh bug, broken separators)
• Spec updates: §6.6.2 IsSanctionedSingleUnitIdentifier (Table 2) and AvailableCanonicalUnits() return set

#Appeal

Energy units have significantly broader utility than existing sanctioned units like stone (UK/Ireland body weight), acre (land area), or fluid-ounce (regional volume measurement), with universal SI standardization and rapidly growing web-facing applications:

• Electric Vehicles: Projected to reach 40M annual sales by 2030^[2] (charging networks: ChargePoint 1M+ sessions/month^[3], EVgo 1.4M+ drivers^[4])
• Building Energy Management: Mandated by EU EPBD directive^[1]
• Smart Home Market: $101B in 2024^[5], projected to reach $226B by 2032 (Home Assistant: 2M+ installations^[6])
• Energy Utility Portals: Major US utilities (PG&E: 16M^[7], SCE: 15M^[8] people served) provide kWh-based web dashboards

#Community Support

Issue #739 has received 15 👍 reactions. There is also a thread on Discourse.

#CLDR

TC39-TG2 has recommended adding energy unit preference data to CLDR as the next step for advancing this proposal. Once this data exists in CLDR, the Stage 1 Smart Unit Preferences proposal would bring locale-aware automatic unit selection to ECMAScript — including magnitude-based scaling via CLDR's geq thresholds.

#Unit Identifier Availability

#Future Considerations

If watt-hour is added to CLDR, it would also enable battery capacity formatting (Wh for laptops and portable devices). See Why watt-hour?

Additional units could be considered in future proposals if demand emerges:

#Defined in CLDR:

• megawatt - Industrial and power generation facilities
• gigawatt - Large-scale power infrastructure
• milliwatt - Low-power electronics

#Not currently in CLDR:

• watt-hour - Base unit for energy scaling. See Why watt-hour?
• megawatt-hour - Utility-scale energy measurement
• gigawatt-hour - Utility-scale energy measurement
• milliampere-hour – mAh used for electronics and batteries

#Lower priority:

• joule, kilojoule - Scientific applications (separate domain)
• british-thermal-unit - HVAC
• horsepower - Automotive (niche web usage)
• calorie, kilocalorie, foodcalorie - Nutrition (separate domain)

Note: Energy price comparison (currency/kWh) is a major consumer-facing use case, but ECMA-402 does not currently support compound currency-per-unit formatting.

#FAQ

#Why these three units?

These cover the overwhelming majority of consumer-facing energy applications in web development. Starting focused allows faster adoption, and all three units are already defined with production-quality formatting in CLDR.

#Why watt-hour?

watt-hour is not yet defined as an explicit unit in CLDR, so this proposal starts with the three units that have production-quality CLDR support today. If watt-hour were added to CLDR, it could be included in ECMA-402 as well — and there are good reasons to consider it:

It is the natural base unit for energy scaling. watt-hour would enable the full prefix chain — Wh, kWh, MWh, GWh. Real-world applications span this entire range: from Wh for device consumption (HA thread) to GWh for grid-scale reporting (Electricity Maps). If the Smart Unit Preferences proposal (Stage 1) lands, watt-hour in CLDR would give energy units automatic magnitude-based scaling — without it, energy would be one of the few common measurement domains without proper scaling support.

The current compound construction produces suboptimal formatting. CLDR can construct watt-hour from components (power-watt + duration-hour), but the result is not production-quality:

The constructed format uses a separator (⋅) and hr instead of the natural Wh. Other locales have similar issues (German: W⋅Std. instead of Wh). CLDR-17881 recognizes that commonly-used compound units should have explicit definitions for better formatting.

#Won't this increase bundle sizes?

These units are defined in CLDR with localization across all supported locales. Browsers may need to ship additional translation strings for the three units. However, the per-unit data is small (unit names, abbreviations, and grammatical forms), and three units represent a minimal addition.

#References

• CLDR-19201: https://unicode-org.atlassian.net/browse/CLDR-19201
• Smart Unit Preferences (Stage 1): https://github.com/tc39/proposal-smart-unit-preferences
• Issue #739: https://github.com/tc39/ecma402/issues/739
• Issue #605: https://github.com/tc39/ecma402/issues/605 (related: metric-ton, cubic units)
• CLDR Unit Validity: https://github.com/unicode-org/cldr/blob/main/common/validity/unit.xml
• CLDR Unit Preferences: https://www.unicode.org/cldr/charts/45/supplemental/unit_preferences.html
• ECMA-402 Spec: https://tc39.es/ecma402/