Intl.DateTimeFormat Object (JavaScript)

Provides locale-specific date and time formatting.

Syntax

dateTimeFormatObj = new Intl.DateTimeFormat([locales][, options])  

Parameters

dateTimeFormatObj
Required. The variable name to assign the DateTimeFormat 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 formatting options for the date and time. 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 DateTimeFormat, you may add the -u subtag in the locale string to include one or both of the following Unicode extensions:

• -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.

• -ca to specify a calendar: language-region-u-ca-calendar

  where calendar may be one of the following: buddhist, chinese, gregory, islamic, islamicc, japanese.

  The options parameter may include the following properties:

The default values for weekday, era, year, month, day, hour, minute, and second are undefined. If you don't set these properties, "numeric" formatting is used for year, month, and day.

Each locale must support, at minimum, the following formats:

• weekday, year, month, day, hour, minute, second

• weekday, year, month, day

• year, month, day

• year, month

• month, day

• hour, minute, second

• hour, minute

Properties

The following table lists the properties of the DateTimeFormat object.

Methods

The following table lists the methods of the DateTimeFormat object.

Example

The following example shows the result of passing a date object to DateTimeFormat using different locales.

var date = new Date(Date.UTC(2013, 1, 1, 14, 0, 0));  
var options = { weekday: "long", year: "numeric", month: "short",  
    day: "numeric" };  

if (console && console.log) {  
    console.log(new Intl.DateTimeFormat("en-US").format(date));  
    // Returns ‎2‎/‎1‎/‎2013  
    console.log(new Intl.DateTimeFormat("ja-JP").format(date));  
    // Returns ‎2013‎年‎2‎月‎1‎日  
    console.log(new Intl.DateTimeFormat("ar-SA", options).format(date));  
    // Returns ‏الجمعة‏, ‏٢٠‏ ‏ربيع الأول‏, ‏١٤٣٤  
    console.log(new Intl.DateTimeFormat("hi-IN", options).format(date));  
    // Returns ‎शुक्रवार‎, ‎01‎ ‎फरवरी‎ ‎2013  
}  

Example

The following example creates a DateTimeFormat object that specifies the current weekday in long format using the Arabic (Saudi Arabia) locale, the Islamic calendar, and the Latin numbering system.

var dtf = new Intl.DateTimeFormat(["ar-SA-u-ca-islamic-nu-latn"], {  
    weekday: "long",  
    year: "numeric",  
    day: "numeric",  
    month: "long"  
});   

If (console && console.log) {  
    console.log(dtf.format(new Date()));  
    // Returns ‏الجمعة‏, ‏19‏ ‏رمضان‏, ‏1434  
}  

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 (Date)
toLocaleDateString Method (Date)
toLocaleTimeString Method (Date)
Intl.Collator Object
Intl.NumberFormat Object