The formatRangeToParts() method of Intl.NumberFormat instances returns an Array of objects containing the locale-specific tokens from which it is possible to build custom strings while preserving the locale-specific parts. This makes it possible to provide locale-aware custom formatting ranges of number strings.

Syntax

formatRangeToParts(startRange, endRange)

Parameters

• startRange

  • : A Number or BigInt.

• endRange

  • : A Number or BigInt.

Return value

An Array of objects containing the formatted range of numbers in parts.

The structure of the returned looks like this:

[
  { type: "integer", value: "3", source: "startRange" },
  { type: "literal", value: "-", source: "shared" },
  { type: "integer", value: "5", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "currency", value: "€", source: "shared" },
];

Possible values for the type property include:

• currency
  • : The currency string, such as the symbols "$" and "€" or the name "Dollar", "Euro", depending on how currencyDisplay is specified.
• decimal
  • : The decimal separator string (".").
• fraction
  • : The fraction number.
• group
  • : The group separator string (",").
• infinity
  • : The Infinity string ("∞").
• integer
  • : The integer number.
• literal
  • : Any literal strings or whitespace in the formatted number.
• minusSign
  • : The minus sign string ("-").
• nan
  • : The NaN string ("NaN").
• plusSign
  • : The plus sign string ("+").
• percentSign
  • : The percent sign string ("%").
• unit
  • : The unit string, such as the "l" or "litres", depending on how unitDisplay is specified.

Possible values for the source property include:

• startRange
  • : The object is the start part of the range.
• endRange
  • : The object is the end part of the range.
• shared
  • : The object is a "shared" part of the range, such as a separator or currency.

Exceptions

• RangeError
  • : Thrown if startRange is less than endRange, or either value is NaN.
• TypeError
  • : Thrown if either startRange or endRange is undefined.

Examples

Comparing formatRange and formatRangeToParts

NumberFormat outputs localized, opaque strings that cannot be manipulated directly:

const startRange = 3500;
const endRange = 9500;

const formatter = new Intl.NumberFormat("de-DE", {
  style: "currency",
  currency: "EUR",
});

console.log(formatter.formatRange(startRange, endRange));
// "3.500,00–9.500,00 €"

However, for many user interfaces there is a need to customize the formatting of this string. The formatRangeToParts method enables locale-aware formatting of strings produced by NumberFormat formatters by providing you the string in parts:

console.log(formatter.formatRangeToParts(startRange, endRange));

// return value:
[
  { type: "integer", value: "3", source: "startRange" },
  { type: "group", value: ".", source: "startRange" },
  { type: "integer", value: "500", source: "startRange" },
  { type: "decimal", value: ",", source: "startRange" },
  { type: "fraction", value: "00", source: "startRange" },
  { type: "literal", value: "–", source: "shared" },
  { type: "integer", value: "9", source: "endRange" },
  { type: "group", value: ".", source: "endRange" },
  { type: "integer", value: "500", source: "endRange" },
  { type: "decimal", value: ",", source: "endRange" },
  { type: "fraction", value: "00", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "currency", value: "€", source: "shared" },
];

Specifications

Browser compatibility

See also

• Intl.NumberFormat
• Intl.NumberFormat.prototype.format()
• Intl.DateTimeFormat.prototype.formatRangeToParts()