Intl.NumberFormat Object (JavaScript)

Provides locale-specific number formatting.

Syntax

numberFormatObj = new Intl.NumberFormat([locales][, options])  

Parameters

numberFormatObj
Required. The variable name to assign the NumberFormat object to.

locales
Optional. An array of locale strings that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used. See the Remarks section for more information.

options
Optional. An object that contains one or more properties that specify number formatting options. See the Remarks section for details.

Remarks

The locales parameter must conform to BCP 47 language or locale tags such as "en-US" and "zh-CN". The tag may include language, region, country, and variant. For examples of language tags, see Appendix A of BCP 47. For NumberFormat, you may add the -u subtag followed by -nu to specify a numbering system extension:

"language-region-u-nu-numberingsystem"

where numberingsystem may be one of the following: arab, arabext, bali, beng, deva, fullwide, gujr, guru, hanidec, khmr, knda, laoo, latn, limb, mylm, mong, mymr, orya, tamldec, telu, thai, tibt.

The options parameter may include the following properties:

Property Description Possible values Default value
localeMatcher Specifies the locale-matching algorithm to use. "lookup", "best fit" "best fit"
style Specifies the number format style. "decimal", "percent", "currency" "decimal"
currency Specifies the ISO 4217 currency value as an alphabetic code. If the style is set to "currency", this value is required. See the ISO currency and funds code list. undefined
currencyDisplay Specifies whether to display the currency as an ISO 4217 alphabetic currency code, a localized currency symbol, or a localized currency name. This value is used only if style is set to "currency". "code", "symbol", "name" "symbol"
useGrouping Specifies whether a grouping separator should be used. true, false true.
minimumIntegerDigits Specifies the minimum number of integral digits to use. 1 to 21. 21
minimumFractionDigits . Specifies the minimum number of fractional digits to be used. 0 to 20. 0
maximumFractionDigits Specifies the maximum number of fractional digits to be used. This value can range from minimumFractionDigits to 20. 20.
minimumSignificantDigits Specifies the minimum number of fractional digits to be shown. This value can range from 1 to 21. 1
maximumSignificantDigits Specifies the maximum number of fractional digits to be shown. This value can range from minimumSignificantDigits to 21. 21

Properties

The following table lists the properties of the NumberFormat object.

Property Description
constructor Specifies the function that creates a number formatter object.
format Returns a function that formats a number by using the number formatter settings.
prototype Returns a reference to the prototype for a number formatter.

Methods

The following table lists the methods of the NumberFormat object.

Method Description
resolvedOptions Returns an object that contains the properties and values of the number formatter object.

Example

The following example creates a NumberFormat object for the en-US locale with the specified formatting options.

var nf = new Intl.NumberFormat(["en-US"], {  
    style: "currency",  
    currency: "CNY",  
    currencyDisplay: "symbol",  
    maximumFractionDigit: 1  
});  

if (console && console.log) {  
    console.log(nf.format(100)); // Returns ¥100.00  
}  

Example

The following examples show the result from using several different locales and options.

var number = 123456789;  
var options1 = { style: "percent" };  
var options2 = { style: "currency", currency: "INR" };  

if (console && console.log) {  
    console.log(new Intl.NumberFormat("en-US").format(number));  
    // Returns 123,456,789  
    console.log(new Intl.NumberFormat("ja-JP").format(number));  
    // Returns 123,456,789  
    console.log(new Intl.NumberFormat("ar-SA", options1).format(number));  
    // Returns ١٢,٣٤٥,٦٧٨,٩٠٠ %  
    console.log(new Intl.NumberFormat("hi-IN", options2).format(number));  
    // Returns ₹ 12,34,56,789.00  
}  

Requirements

Supported in the Internet Explorer 11 standards document mode. Also supported in Store apps (Windows 8.1 and Windows Phone 8.1). See Version Information.
Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards, Internet Explorer 9 standards, Internet Explorer 10 standards. Not supported in Windows 8.

See Also

toLocaleString (Number)
Intl.Collator Object
Intl.DateTimeFormat Object