Intl.NumberFormat.prototype.formatToParts()
The formatToParts()
method of Intl.NumberFormat
instances allows locale-aware formatting of strings produced by this Intl.NumberFormat
object.
Try it
Syntax
js
formatToParts()
formatToParts(number)
Parameters
Return value
An Array
of objects containing the formatted number in parts.
Description
The formatToParts()
method is useful for custom formatting of number
strings. It returns an Array
of objects containing the locale-specific
tokens from which it possible to build custom strings while preserving the
locale-specific parts. The structure the formatToParts()
method returns,
looks like this:
js
[
{ type: "integer", value: "3" },
{ type: "group", value: "." },
{ type: "integer", value: "500" },
];
Possible types are the following:
compact
-
The exponent in
"long"
or"short"
form, depending on howcompactDisplay
(which defaults toshort
) is specified whennotation
is set tocompact
. 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 (".").
exponentInteger
-
The exponent integer value, when
notation
is set toscientific
orengineering
. exponentMinusSign
-
The exponent minus sign string ("-").
exponentSeparator
-
The exponent separator, when
notation
is set toscientific
orengineering
. 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. unknown
-
The string for
unknown
type results.
Examples
Comparing format and formatToParts
NumberFormat
outputs localized, opaque strings that cannot be manipulated
directly:
js
const number = 3500;
const formatter = new Intl.NumberFormat("de-DE", {
style: "currency",
currency: "EUR",
});
formatter.format(number);
// "3.500,00 €"
However, in many User Interfaces there is a desire to customize the formatting of this
string. The formatToParts
method enables locale-aware formatting of
strings produced by NumberFormat
formatters by providing you the string
in parts:
js
formatter.formatToParts(number);
// return value:
[
{ type: "integer", value: "3" },
{ type: "group", value: "." },
{ type: "integer", value: "500" },
{ type: "decimal", value: "," },
{ type: "fraction", value: "00" },
{ type: "literal", value: " " },
{ type: "currency", value: "€" },
];
Now the information is available separately and it can be formatted and concatenated
again in a customized way. For example by using Array.prototype.map()
,
arrow functions,
a switch statement,
template literals, and Array.prototype.reduce()
.
js
const numberString = formatter
.formatToParts(number)
.map(({ type, value }) => {
switch (type) {
case "currency":
return `<strong>${value}</strong>`;
default:
return value;
}
})
.reduce((string, part) => string + part);
This will make the currency bold, when using the formatToParts()
method.
js
console.log(numberString);
// "3.500,00 <strong>€</strong>"
Specifications
Specification |
---|
ECMAScript Internationalization API Specification # sec-intl.numberformat.prototype.formattoparts |
Browser compatibility
BCD tables only load in the browser