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 thelocales
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
andfalse
; the default is locale dependent. This option overrides thehc
language tag and/or thehourCycle
option in case both are present. hourCycle
- The hour cycle to use. Possible values are "
h11
", "h12
", "h23
", or "h24
". This option overrides thehc
language tag, if both are present, and thehour12
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 alsoT
).
- "
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 alsoM
).
- "
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 areundefined
, thenyear
,month
, andday
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
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DateTimeFormat | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android Full support 4.4 | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android Full support 14 | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs Full support Yes |
dateStyle | Chrome Full support 76 | Edge No support No | Firefox No support No | IE No support No | Opera Full support 63 | Safari ? | WebView Android Full support 76 | Chrome Android Full support 76 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android No support No | nodejs Full support Yes |
format | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android ? | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
formatRange | Chrome Full support 76 | Edge No support No | Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android Full support 76 | Chrome Android Full support 76 | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
formatRangeToParts | Chrome Full support 76 | Edge No support No | Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android Full support 76 | Chrome Android Full support 76 | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
formatToParts | Chrome
Full support
57
| Edge Full support 18 | Firefox Full support 51 | IE No support No | Opera Full support Yes | Safari Full support 11 | WebView Android
Full support
57
| Chrome Android
Full support
57
| Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 11 | Samsung Internet Android
Full support
7.0
| nodejs Full support Yes |
hourCycle | Chrome Full support 73 | Edge Full support 18 | Firefox Full support 58 | IE No support No | Opera Full support 60 | Safari ? | WebView Android Full support 73 | Chrome Android Full support 73 | Firefox Android Full support 58 | Opera Android Full support 52 | Safari iOS ? | Samsung Internet Android No support No | nodejs ? |
IANA time zone names in timeZone option | Chrome Full support 24 | Edge Full support 14 | Firefox Full support 52 | IE No support No | Opera Full support 15 | Safari Full support 10 | WebView Android Full support 37 | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android ? | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
prototype | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android ? | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
resolvedOptions | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android ? | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
supportedLocalesOf | Chrome Full support 24 | Edge Full support 12 | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Firefox Android Full support 56 | Opera Android ? | Safari iOS Full support 10 | Samsung Internet Android Full support 1.5 | nodejs ? |
timeStyle | Chrome Full support 76 | Edge No support No | Firefox No support No | IE No support No | Opera Full support 63 | Safari ? | WebView Android Full support 76 | Chrome Android Full support 76 | Firefox Android No support No | Opera Android No support No | Safari iOS ? | Samsung Internet Android No support No | nodejs Full support Yes |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.
- See implementation notes.
See also
- Introduction: The ECMAScript Internationalization API
- Constructors
- Methods