Intl.DateTimeFormat Object (JavaScript)

Provides locale-specific date and time formatting.


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


Required. The variable name to assign the DateTimeFormat object to.

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.

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


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:

Property Description Possible values Default value
localeMatcher Specifies the locale-matching algorithm to use. "lookup","best fit" "best fit"
formatMatcher Specifies the format-matching algorithm to use. "basic", "best fit" "best fit"
hour12 Specifies whether to use a 12-hour format for hours. true (for 12-hour format), false (for 24-hour format)
timeZone Specifies the time zone. At minimum, "UTC" is always supported. A timezone value such as "UTC". "UTC"
weekday Specifies formatting of the weekday. "narrow", "short", "long". undefined
era Specifies formatting of the era. "narrow", "short", "long" undefined
year Specifies formatting of the year. "2-digit", "numeric" undefined or "numeric"
month Specifies formatting of the month. "2-digit", "numeric", "narrow", "short", "long" undefined or "numeric"
day Specifies formatting of the day. "2-digit", "numeric" undefined or "numeric"
hour Specifies formatting of the hour. "2-digit", "numeric" undefined
minute Specifies formatting of the minute. "2-digit", "numeric" undefined
second Specifies formatting of the second. "2-digit", "numeric" undefined
timeZoneName Specifies formatting of the time zone. This property is not currently supported. "short", "long". This property is not currently supported.

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


The following table lists the properties of the DateTimeFormat object.

Property Description
constructor Specifies the function that creates a date/time formatter object.
format Returns a function that formats a locale-specific date by using the date/time formatter settings.
prototype Returns a reference to the prototype for a date/time formatter.


The following table lists the methods of the DateTimeFormat object.

Method Description
resolvedOptions Returns an object that contains the properties and values of the date/time formatter object.


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  


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  


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