Intl.NumberFormat.prototype.formatRangeToParts()
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
,BigInt
, or string, to format. Strings are parsed in the same way as in number conversion, except thatformatRangeToParts()
will use the exact value that the string represents, avoiding loss of precision during implicitly conversion to a number. endRange
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.
-
The object is a "shared" part of the range, such as a separator or currency.
Exceptions
RangeError
-
Thrown if either
startRange
orendRange
isNaN
or an inconvertible string. TypeError
-
Thrown if either
startRange
orendRange
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
Specification |
---|
ECMAScript Internationalization API Specification # sec-intl.numberformat.prototype.formatrangetoparts |
Browser compatibility
BCD tables only load in the browser