Skip to content
Proposal for new options and restructured spec for Intl.NumberFormat
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
section6 Allow only simple units to be numerators and denominators. Fixes #24. Feb 27, 2019
.gitattributes Add .gitattributes Sep 25, 2017
.gitignore Adding section to spec for unit resolution. Jun 12, 2018
LICENSE Initial commit Jul 25, 2017
package.json Adding Section 6 diff. Moving files around. Fixing index.html links. Oct 30, 2018

Intl.NumberFormat Unified API Proposal

TC39 Stage 2 Proposal

TC39 Stage 3 Proposal

View Spec

Background / Motivation

There are many requests for adding number-formatting-related features to ECMA-402 (the JavaScript Intl standard library). These include:

These features are important to both end users and to Google. Since most of these features require carrying along large amounts of locale data for proper i18n support, exposing these features via a JavaScript API reduces bandwidth and lowers the barrier to entry for i18n best practices.

Rather than complicate Intl with more constructors with heavilly overlapping functionality, this proposal is to restructure the spec of Intl.NumberFormat to make it more easilly support additional features in a "unified" way.

Additional background: prior discussion

I. Spec Cleanup

Certain sections of the spec have been refactored with the following objectives:

In addition, one missing option is added to the existing currencyDisplay setting: "narrow-symbol", which uses the CLDR narrow-format symbol:

(100).toLocaleString("en-CA", {
    style: "currency",
    currency: "USD",
    currencyDisplay: "narrow-symbol"
// ==> "$100" (rather than "US$100")

II. Units

Units of measurement can be formatted as follows:

(9.81).toLocaleString("en-US", {
    style: "unit",
    unit: "meter-per-second-squared",
    unitDisplay: "short"
// ==> "9.81 m/s²"

The syntax was discussed in #3.

  • style receives the string value "unit"
  • unit receives a string core unit identifier, defined in UTS #35, Part 2, Section 6. See also the full list of unit identifiers.
  • unitDisplay, named after the corresponding setting for currencies, currencyDisplay, takes either "narrow", "short", or "long".

III. Scientific and Compact Notation

Scientific and compact notation are represented by the new option notation and can be formatted as follows:

(987654321).toLocaleString("en-US", {
    notation: "scientific"
// ==> 9.877E8

(987654321).toLocaleString("en-US", {
    notation: "engineering"
// ==> 987.7E6

(987654321).toLocaleString("en-US", {
    notation: "compact",
    compactDisplay: "long"
// ==> 987.7 million

The syntax was discussed in #5.

  • notation takes either "scientific", "engineering", "compact", or "plain"
  • compactDisplay, used only when notation is "compact", takes either "short" or "long"

Rounding-related settings (min/max integer/fraction digits) are applied after the number is scaled according to the chosen notation.

When notation is "compact" and there are no user-specified rounding options, a special compact notation rounding strategy is used: round to the nearest integer, but always keep 2 significant digits. For example, 123.4K rounds to 123K, and 1.234K rounds to 1.2K. The user can determine that the compact rounding strategy is being used in the resolvedOptions if notation is "compact" and none of the rounding settings are present.

Notation styles are allowed to be combined with other options:

(299792458).toLocaleString("en-US", {
    notation: "scientific",
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
    style: "unit",
    unit: "speed-meter-per-second"
// ==> 3.00E8 m/s

IV. Sign Display

The sign can be displayed on positive numbers:

(55).toLocaleString("en-US", {
    signDisplay: "always"
// ==> +55

Currency accounting sign display is also supported via a new option. In many locales, accounting format means to wrap the number with parentheses instead of appending a minus sign. For example:

(-100).toLocaleString("bn", {
    style: "currency",
    currency: "EUR",
    currencySign: "accounting"
// ==> (১০০.০০€)

The syntax was discussed in #6:

  • signDisplay: "auto" (default), "always", "never", "except-zero"
    • See examples below.
  • currencySign: "standard" (default), "accounting"
    • "accounting" enables the accounting format on currency values, as shown in the example above. "standard", the default value, disables accounting formats.

Examples of signDisplay choices with Latin digits:

signDisplay -1 -0 0 1
auto -1 -0 0 1
always -1 -0 +0 +1
never 1 0 0 1
except-zero -1 -0 0 +1

Examples of signDisplay choices with Latin digits when currencySign is "accounting":

signDisplay -1 -0 0 1
auto (1.00) (0.00) 0.00 1.00
always (1.00) (0.00) +0.00 +1.00
never 1.00 0.00 0.00 1.00
except-zero (1.00) (0.00) 0.00 +1.00

As usual, this may be combined with other options.

(0.55).toLocaleString("en-US", {
    style: "percent",
    signDisplay: "except-zero"
// ==> +55%
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.