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 in parts. Each object has three properties, type
, value
, and source
, each containing a string. The string concatenation of value
, in the order provided, will result in the same string as formatRange()
. The type
may have the same values as formatToParts()
. The source
can be one of the following:
startRange
-
The token is a part of the start number.
endRange
-
The token is a part of the end number.
-
The token is shared between the start and end; for example, the currency symbol. All literals that are part of the range pattern itself, such as the
"–"
separator, are also marked asshared
.
If the start and end numbers are equivalent, then the output has the same list of tokens as calling formatToParts()
on the start number, with all tokens marked as source: "shared"
.
Exceptions
RangeError
-
Thrown if either
startRange
orendRange
isNaN
or an inconvertible string. TypeError
-
Thrown if either
startRange
orendRange
is undefined.
Examples
Using formatRangeToParts()
The formatRange()
method 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, in many user interfaces you may want to customize the formatting of this string, or interleave it with other texts. The formatRangeToParts()
method produces the same information 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