Intl.DateTimeFormat

You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!

The Intl.DateTimeFormat object is a constructor for objects that enable language-sensitive date and time formatting. 

Syntax

new Intl.DateTimeFormat([locales[, options]])
Intl.DateTimeFormat.call(this[, locales[, options]])

Parameters

locales Optional

A string with a BCP 47 language tag, or an array of such strings. To use the browser's default locale, omit this argument or pass undefined. Unicode extension are supported (for example "en-US-u-ca-buddhist"). For the general form and interpretation of the locales argument, see the Intl page. 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", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc".
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"
timeStyle
The time formatting style to use when calling format(). Possible values include:
  • "full"
  • "long"
  • "medium"
  • "short
fractionalSecondDigits
The number of fractional seconds to apply when calling format(). Valid values are 0-3.
calendar
Calendar. Possible values include: "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", " hebrew", "indian", "islamic", "iso8601", " japanese", "persian", "roc".
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 will 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.

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 locales (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., 2)
  • "2-digit" (e.g., 02)
  • "long" (e.g., March)
  • "short" (e.g., Mar)
  • "narrow" (e.g., M). Two months may have the same narrow style for some locales (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".
timeZoneName
The representation of the time zone name. Possible values are:
  • "long" (e.g., British Summer Time)
  • "short" (e.g., GMT+1)

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

Description

Properties

Intl.DateTimeFormat.prototype
Allows the addition of properties to all objects.

Methods

Intl.DateTimeFormat.supportedLocalesOf()
Returns an array containing those of the provided locales that are supported without having to fall back to the runtime's default locale.

DateTimeFormat instances

Properties

DateTimeFormat instances inherit the following properties from their prototype:

Intl.DateTimeFormat.prototype.constructor
A reference to Intl.DateTimeFormat.

Methods

DateTimeFormat instances inherit the following methods from their prototype:

Intl.DateTimeFormat.prototype.format()
Getter function that formats a date according to the locale and formatting options of this DateTimeFormat object.
Intl.DateTimeFormat.prototype.formatToParts()
Returns an Array of objects representing the date string in parts that can be used for custom locale-aware formatting.
Intl.DateTimeFormat.prototype.resolvedOptions()
Returns a new object with properties reflecting the locale and formatting options computed during initialization of the object.
Intl.DateTimeFormat.prototype.formatRange()
This method receives two Dates and formats the date range in the most concise way based on the locale and options provided when instantiating DateTimeFormat.
Intl.DateTimeFormat.prototype.formatRangeToParts()
This method receives two Dates and returns an Array of objects containing the locale-specific tokens representing each part of the formatted date range.

Examples

Using DateTimeFormat

In basic use without specifying a locale, DateTimeFormat uses the default locale and default options.

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(new Intl.DateTimeFormat().format(date));
// → "12/19/2012" if run with en-US locale (language) and time zone America/Los_Angeles (UTC-0800)

Using locales

This example shows some of the variations in localized date and time formats. In order to get the format of the language used in the user interface of your application, make sure to specify that language (and possibly some fallback languages) using the locales argument:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Results below use the time zone of America/Los_Angeles (UTC-0800, Pacific Standard Time)

// US English uses month-day-year order
console.log(new Intl.DateTimeFormat('en-US').format(date));
// → "12/19/2012"

// British English uses day-month-year order
console.log(new Intl.DateTimeFormat('en-GB').format(date));
// → "19/12/2012"

// Korean uses year-month-day order
console.log(new Intl.DateTimeFormat('ko-KR').format(date));
// → "2012. 12. 19."

// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(new Intl.DateTimeFormat('ar-EG').format(date));
// → "١٩‏/١٢‏/٢٠١٢"

// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(new Intl.DateTimeFormat('ja-JP-u-ca-japanese').format(date));
// → "24/12/19"

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(new Intl.DateTimeFormat(['ban', 'id']).format(date));
// → "19/12/2012"

Using options

The date and time formats can be customized using the options argument:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// request a weekday along with a long date
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(new Intl.DateTimeFormat('de-DE', options).format(date));
// → "Donnerstag, 20. Dezember 2012"

// an application may want to use UTC and make that visible
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// → "Thursday, December 20, 2012, GMT"

// sometimes you want to be more precise
options = {
  hour: 'numeric', minute: 'numeric', second: 'numeric', 
  timeZone: 'Australia/Sydney',
  timeZoneName: 'short'
};
console.log(new Intl.DateTimeFormat('en-AU', options).format(date));
// → "2:00:00 pm AEDT"

// sometimes even the US needs 24-hour time
options = {
  year: 'numeric', month: 'numeric', day: 'numeric',
  hour: 'numeric', minute: 'numeric', second: 'numeric',
  hour12: false,
  timeZone: 'America/Los_Angeles' 
};
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// → "12/19/2012, 19:00:00"

// to specify options but use the browser's default locale, use 'default'
console.log(new Intl.DateTimeFormat('default', options).format(date));
// → "12/19/2012, 19:00:00"

The used calendar and numbering formats can also be set independently via options arguments:

var options = {calendar: 'chinese', numberingSystem: 'arab'};
var dateFormat = new Intl.DateTimeFormat('default', options);
var usedOptions = dateFormat.resolvedOptions();

console.log(usedOptions.calendar);
// → "chinese"

console.log(usedOptions.numberingSystem);
// → "arab"

console.log(options.timeZone);
// → "America/New_York" (the users default timezone)

Specifications

Specification Status Comment
ECMAScript Internationalization API 4.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Draft
ECMAScript Internationalization API 2.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Standard
ECMAScript Internationalization API 1.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Standard Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
DateTimeFormatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 26Firefox Android Full support 56Opera Android Full support 14Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support Yes
dateStyleChrome Full support 76Edge No support NoFirefox No support NoIE No support NoOpera Full support 63Safari ? WebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android No support Nonodejs Full support Yes
formatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
formatRangeChrome Full support 76Edge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support Nonodejs No support No
formatRangeToPartsChrome Full support 76Edge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support Nonodejs No support No
formatToPartsChrome Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Edge Full support 18Firefox Full support 51IE No support NoOpera Full support YesSafari Full support 11WebView Android Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Chrome Android Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Firefox Android Full support 56Opera Android No support NoSafari iOS Full support 11Samsung Internet Android Full support 7.0
Notes
Full support 7.0
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
nodejs Full support Yes
hourCycleChrome Full support 73Edge Full support 18Firefox Full support 58IE No support NoOpera Full support 60Safari ? WebView Android Full support 73Chrome Android Full support 73Firefox Android Full support 58Opera Android Full support 52Safari iOS ? Samsung Internet Android No support Nonodejs ?
IANA time zone names in timeZone optionChrome Full support 24Edge Full support 14Firefox Full support 52IE No support NoOpera Full support 15Safari Full support 10WebView Android Full support 37Chrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
prototypeChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
resolvedOptionsChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
supportedLocalesOfChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support 1.5nodejs ?
timeStyleChrome Full support 76Edge No support NoFirefox No support NoIE No support NoOpera Full support 63Safari ? WebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android No support Nonodejs Full support Yes

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

See also