2023/3/13 02:51 Intl.
DateTimeFormat() constructor - JavaScript | MDN
[Link]() constructor
The [Link]() constructor creates [Link] objects that enable language-sensitive date and time formatting.
Try it
JavaScript Demo: [Link]
1 const date = new Date([Link](2020, 11, 20, 3, 23, 16, 738));
2 // Results below assume UTC timezone - your results may vary
3
4 // Specify default date formatting for language (locale)
5 [Link](new [Link]('en-US').format(date));
6 // Expected output: "12/20/2020"
7
8 // Specify default date formatting for language with a fallback language (in this case Indone
9 [Link](new [Link](['ban', 'id']).format(date));
10 // Expected output: "20/12/2020"
11
12 // Specify date and time format using "style" options (i.e. full, long, medium, short)
13 [Link](new [Link]('en-GB', { dateStyle: 'full', timeStyle: 'long', timeZone
14 // Expected output: "Sunday, 20 December 2020 at 14:23:16 GMT+11"
15
Run › Reset
Syntax
new [Link]()
new [Link](locales)
new [Link](locales, options)
[Link]()
[Link](locales)
[Link](locales, options)
Note: [Link]() can be called with or without new . Both create a new [Link] instance. However, there's
a special behavior when it's called without new and the this value is another [Link] instance; see Return value.
Parameters
locales Optional
[Link] 1/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see
Locale identification and negotiation. The following Unicode extension keys are allowed:
nu
Numbering system. Possible values include: "arab" , "arabext" , "bali" , "beng" , "deva" , "fullwide" , "gujr" , "guru" , "hanidec" , "khmr" ,
"knda" , "laoo" , "latn" , "limb" , "mlym" , "mong" , "mymr" , "orya" , "tamldec" , "telu" , "thai" , "tibt" .
ca
Calendar. Possible values include: "buddhist" , "chinese" , "coptic" , "dangi" , "ethioaa" , "ethiopic" , "gregory" , "hebrew" , "indian" ,
"islamic" , "islamic-umalqura" , "islamic-tbla" , "islamic-civil" , "islamic-rgsa" , "iso8601" , "japanese" , "persian" , "roc" , "islamicc" .
Warning: The islamicc calendar key has been deprecated. Please use islamic-civil .
hc
Hour cycle. Possible values include: "h11" , "h12" , "h23" , "h24" .
options Optional
An object with some or all of the following properties:
dateStyle
The date formatting style to use when calling format() . Possible values include:
"full"
"long"
"medium"
"short"
Note: dateStyle can be used with timeStyle , but not with other options (e.g. weekday , hour , month , etc.).
timeStyle
The time formatting style to use when calling format() . Possible values include:
"full"
"long"
"medium"
"short"
Note: timeStyle can be used with dateStyle , but not with other options (e.g. weekday , hour , month , etc.).
calendar
Calendar. Possible values include: "buddhist" , "chinese" , "coptic" , "dangi" , "ethioaa" , "ethiopic" , "gregory" , "hebrew" , "indian" ,
"islamic" , "islamic-umalqura" , "islamic-tbla" , "islamic-civil" , "islamic-rgsa" , "iso8601" , "japanese" , "persian" , "roc" , "islamicc" .
Warning: The islamicc calendar key has been deprecated. Please use islamic-civil .
[Link] 2/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
dayPeriod
The formatting style used for day periods like "in the morning", "am", "noon", "n" etc. Possible values include: "narrow" , "short" , "long" .
Note:
This option only has an effect if a 12-hour clock is used.
Many locales use the same string irrespective of the width specified.
numberingSystem
Numbering System. Possible values include: "arab" , "arabext" , "bali" , "beng" , "deva" , "fullwide" , " gujr ", "guru" , "hanidec" , "khmr" ,
" knda ", "laoo" , "latn" , "limb" , "mlym" , "mong" , "mymr" , "orya" , "tamldec" , "telu" , "thai" , "tibt" .
localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit" ; the default is "best fit" . For information about this
option, see the Intl page.
timeZone
The time zone to use. The only value implementations must recognize is "UTC" ; the default is the runtime's default time zone.
Implementations may also recognize the time zone names of the IANA time zone database , such as "Asia/Shanghai" , "Asia/Kolkata" ,
"America/New_York" .
hour12
Whether to use 12-hour time (as opposed to 24-hour time). Possible values are true and false ; the default is locale dependent. This
option overrides the hc language tag and/or the hourCycle option in case both are present.
hourCycle
The hour cycle to use. Possible values are "h11" , "h12" , "h23" , or "h24" . This option overrides the hc language tag, if both are present,
and the hour12 option takes precedence in case both options have been specified.
formatMatcher
The format matching algorithm to use. Possible values are "basic" and "best fit" ; the default is "best fit" . See the following
paragraphs for information about the use of this property.
The following properties describe the date-time components to use in formatted output, and their desired representations.
Implementations are required to support at least the following subsets:
weekday , year , month , day , hour , minute , second
weekday , year , month , day
year , month , day
year , month
month , day
hour , minute , second
hour , minute
Implementations may support other subsets, and requests wil be negotiated against all available subset-representation combinations to
find the best match. Two algorithms are available for this negotiation and selected by the formatMatcher property: A fully specified "basic"
algorithm and an implementation-dependent "best fit" algorithm.
[Link] 3/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
weekday
The representation of the weekday. Possible values are:
"long" (e.g., Thursday )
"short" (e.g., Thu )
"narrow" (e.g., T ). Two weekdays may have the same narrow style for some lo cales (e.g. Tuesday 's narrow style is also T ).
era
The representation of the era. Possible values are:
"long" (e.g., Anno Domini )
"short" (e.g., AD )
"narrow" (e.g., A )
year
The representation of the year. Possible values are:
"numeric" (e.g., 2012 )
"2-digit" (e.g., 12 )
month
The representation of the month. Possible values are:
"numeric" (e.g., 3 )
"2-digit" (e.g., 03 )
"long" (e.g., March )
"short" (e.g., Mar )
"narrow" (e.g., M ). Two months may have the same narrow style for some lo cales (e.g. May 's narrow style is also M ).
day
The representation of the day. Possible values are:
"numeric" (e.g., 1 )
"2-digit" (e.g., 01 )
hour
The representation of the hour. Possible values are "numeric" , "2-digit" .
minute
The representation of the minute. Possible values are "numeric" , "2-digit" .
second
The representation of the second. Possible values are "numeric" , "2-digit" .
fractionalSecondDigits
The number of digits used to represent fractions of a second (any additional digits are truncated). Possible values are:
0 (Fractio nal part dropped.)
[Link] 4/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
1 (Fractional part represented as 1 digit. For example, 736 is formatted as 7 .)
2 (Fractio nal part represented as 2 digits. For example, 736 is formatted as 73 .)
3 (Fractio nal part represented as 3 digits. For example, 736 is formatted as 736 .)
timeZoneName
The localized representation of the time zone name. Possible values are:
"long" Long lo calized form (e.g., Pacific Standard Time , Nordamerikanische Westküsten-Normalzeit )
"short" Short lo calized form (e.g.: PST , GMT-8 )
"shortOffset" Short lo calized GMT format (e.g., GMT-8 )
"longOffset" Long lo calized GMT format (e.g., GMT-0800 )
"shortGeneric" Short generic non-lo catio n format (e.g.: PT , Los Angeles Zeit ).
"longGeneric" Long generic non-lo catio n format (e.g.: Pacific Time , Nordamerikanische Westküstenzeit )
Note: Timezone display may fall back to another format if a required string is unavailable. For example, the non-location
formats should display the timezone without a specific country/city location like "Pacific Time", but may fall back to a timezone
like "Los Angeles Time".
The default value for each date-time component property is undefined , but if all component properties are undefined , then year , month ,
and day are assumed to be "numeric" .
Return value
A new [Link] object.
Note: The text below describes behavior that is marked by the specification as "optional". It may not work in all environments.
Check the browser compatibility table.
Normally, [Link]() can be called with or without new , and a new [Link] instance is returned in both cases.
However, if the this value is an object that is instanceof [Link] (doesn't necessarily mean it's created via new
[Link] ; just that it has [Link] in its prototype chain), then the value of this is returned instead, with the
newly created [Link] object hidden in a [Symbol(IntlLegacyConstructedSymbol)] property (a unique symbol that's reused
between instances).
const formatter = [Link](
{ __proto__: [Link] },
"en-US",
{ dateStyle: "full" },
);
[Link]([Link](formatter));
// {
// [Symbol(IntlLegacyConstructedSymbol)]: {
// value: DateTimeFormat [[Link]] {},
// writable: false,
// enumerable: false,
// configurable: false
// }
// }
Note that there's only one actual [Link] instance here: the one hidden in [Symbol(IntlLegacyConstructedSymbol)] . Calling the
format() and resolvedOptions() methods on formatter would correctly use the optio ns stored in that instance, but calling all other methods
[Link] 5/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
(e.g. formatRange() ) would fail: "TypeError: formatRange method called on incompatible Object", because those methods don't consult the
hidden instance's options.
This behavior, called ChainDateTimeFormat , does not happen when [Link]() is called without new but with this set to anything
else that's not an instanceof [Link] . If you call it directly as [Link]() , the this value is Intl , and a new
[Link] instance is created normally.
Examples
Using DateTimeFormat
In basic use without specifying a locale, DateTimeFormat uses the default locale and default options.
const date = new Date([Link](2012, 11, 20, 3, 0, 0));
// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
[Link](new [Link]().format(date));
// "12/19/2012" if run with en-US locale (language) and time zone America/Los_Angeles (UTC-0800)
Using timeStyle and dateStyle
const shortTime = new [Link]("en", {
timeStyle: "short",
});
[Link]([Link]([Link]())); // "1:31 PM"
const shortDate = new [Link]("en", {
dateStyle: "short",
});
[Link]([Link]([Link]())); // "07/07/20"
const mediumTime = new [Link]("en", {
timeStyle: "medium",
dateStyle: "short",
});
[Link]([Link]([Link]())); // "07/07/20, 1:31:55 PM"
Using dayPeriod
Use the dayPeriod option to output a string for the times of day ("in the morning", "at night", "noon", etc.). Note, that this only works when
formatting for a 12 hour clock ( hourCycle: 'h12' ) and that for many locales the strings are the same irrespective of the value passed for the
dayPeriod .
const date = [Link](2012, 11, 17, 4, 0, 42);
[Link](
new [Link]("en-GB", {
hour: "numeric",
hourCycle: "h12",
dayPeriod: "short",
timeZone: "UTC",
}).format(date),
);
// 4 at night" (same formatting in en-GB for all dayPeriod values)
[Link](
new [Link]("fr", {
hour: "numeric",
hourCycle: "h12",
dayPeriod: "narrow",
timeZone: "UTC",
[Link] 6/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
}).format(date),
);
// "4 mat." (same output in French for both narrow/short dayPeriod)
[Link](
new [Link]("fr", {
hour: "numeric",
hourCycle: "h12",
dayPeriod: "long",
timeZone: "UTC",
}).format(date),
);
// "4 du matin"
Using timeZoneName
Use the timeZoneName option to output a string for the timezone ("GMT", "Pacific Time", etc.).
const date = [Link](2021, 11, 17, 3, 0, 42);
const timezoneNames = [
"short",
"long",
"shortOffset",
"longOffset",
"shortGeneric",
"longGeneric",
];
for (const zoneName of timezoneNames) {
// Do something with currentValue
const formatter = new [Link]("en-US", {
timeZone: "America/Los_Angeles",
timeZoneName: zoneName,
});
[Link](`${zoneName}: ${[Link](date)}`);
}
// Logs:
// short: 12/16/2021, PST
// long: 12/16/2021, Pacific Standard Time
// shortOffset: 12/16/2021, GMT-8
// longOffset: 12/16/2021, GMT-08:00
// shortGeneric: 12/16/2021, PT
// longGeneric: 12/16/2021, Pacific Time
Specifications
Specification
ECMAScript Internationalization API Specification
# sec-intl-datetimeformat-constructor
Browser compatibility
Report problems with this compatibility data on GitHub
[Link] 7/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
diordn A emorhC
emorhC
xoferiF
arepO
irafaS
e gd E
diordn A emorhC
emorhC
xoferiF
arepO
irafaS
e gd E
Chrome 24 Edge 12 Firefox 29 Opera 15 Safari 10 Chrome 25
DateTimeFormat() constructor Android
Chrome 91 Edge 91 Firefox 54 Opera 77 Safari 14.1 Chrome 91
Supports normative optional Android
ChainDateTimeFormat behavior
Chrome 24 Edge 12 Firefox 29 Opera 15 Safari 10 Chrome 25
locales parameter Android
Chrome 24 Edge 12 Firefox 29 Opera 15 Safari 10 Chrome 25
options parameter Android
Chrome 76 Edge 79 Firefox 79 Opera 63 Safari 14.1 Chrome 76
[Link] parameter Android
Chrome 92 Edge 92 Firefox 90 Opera 78 Safari 14.1 Chrome 92
[Link] parameter Android
Chrome 84 Edge 84 Firefox 84 Opera 70 Safari 14.1 Chrome 84
[Link]
parameter Android
Chrome 73 Edge 18 Firefox 58 Opera 60 Safari 13 Chrome 73
[Link] parameter Android
Chrome 76 Edge 79 Firefox 79 Opera 63 Safari 14.1 Chrome 76
[Link] parameter Android
Chrome 24 Edge 12 Firefox 29 Opera 15 Safari 10 Chrome 25
[Link]
parameter Android
Chrome No Edge No Firefox 91 Opera No Safari 15.4 Chrome No
IANA time zone names in Android
[Link] option
Chrome 24 Edge 12 Firefox 29 Opera 15 Safari 10 Chrome 25
[Link] parameter Android
Chrome 24 Edge 14 Firefox 52 Opera 15 Safari 10 Chrome 25
IANA time zone names in Android
[Link] option
Tip: you can click/tap on a cell for more information.
[Link] 8/9
2023/3/13 02:51 [Link]() constructor - JavaScript | MDN
Full support Partial support No support Deprecated. Not for use in new websites. Has more compatibility info.
See also
[Link]
[Link]()
Intl
This page was last modified on Feb 21, 2023 by MDN contributors.
[Link] 9/9