Intl.DateTimeFormat.prototype.resolvedOptions()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.
The resolvedOptions()
method of Intl.DateTimeFormat
instances returns a new object with properties reflecting the options computed during initialization of this DateTimeFormat
object.
Try it
Syntax
resolvedOptions()
Parameters
None.
Return value
A new object with properties reflecting the options computed during the initialization of this DateTimeFormat
object. The object has the following properties, in the order they are listed:
locale
-
The BCP 47 language tag for the locale actually used, determined by the locale negotiation process. Only the
ca
,hc
, andnu
Unicode extension keys, if requested, may be included in the output. calendar
-
The value provided for this property in the
options
argument, or using the Unicode extension key"ca"
, with default filled in as needed. It is a supported calendar type for this locale. The default is locale dependent. numberingSystem
-
The value provided for this property in the
options
argument, or using the Unicode extension key"nu"
, with default filled in as needed. It is a supported numbering system for this locale. The default is locale dependent. timeZone
-
The value provided for this property in the
options
argument, with default filled in as needed. It is a canonicalized IANA time zone name. The default is the runtime's default time zone.Note: While the IANA database changes from time to time, the Unicode CLDR database (which browsers use) keeps old time zone names for stability purposes. All browsers canonicalize time zone names, but in different directions. For example,
new Intl.DateTimeFormat("en-US", { timeZone: "Europe/Kiev" }).resolvedOptions().timeZone
andnew Intl.DateTimeFormat("en-US", { timeZone: "Europe/Kyiv" }).resolvedOptions().timeZone
will return the same string in the same browser, but maybe different strings in different browsers. SeeIntl.Locale.prototype.getTimeZones
for more information. hourCycle
Optional-
The value provided for this property in the
options
argument, or using the Unicode extension key"hc"
, with default filled in as needed. Ifhour12
was provided in theoptions
, then that overrides otherhourCycle
settings. It is only present if the resolved options also includehour
ortimeStyle
. It is either"h11"
,"h12"
,"h23"
, or"h24"
. The default is locale dependent, although"h24"
is never a default. hour12
Optional-
Calculated from
hourCycle
. It is only present if the resolved options also includehour
ortimeStyle
. It istrue
ifhourCycle
is"h11"
or"h12"
, andfalse
ifhourCycle
is"h23"
or"h24"
. weekday
,era
,year
,month
,day
,dayPeriod
,hour
,minute
,second
,fractionalSecondDigits
,timeZoneName
Optional-
The values resulting from format matching between the corresponding properties in the
options
argument and the available combinations and representations for date-time formatting in the selected locale. Some of these properties may not be present, indicating that the corresponding components will not be represented in formatted output.weekday
,era
, anddayPeriod
are either"narrow"
,"short"
, or"long"
;year
,day
,hour
,minute
, andsecond
are either"numeric"
,"2-digit"
, or"narrow"
;month
is either"numeric"
,"2-digit"
,"narrow"
,"short"
, or"long"
;fractionalSecondDigits
is either1
,2
, or3
;timeZoneName
is either"short"
,"long"
,"shortOffset"
,"longOffset"
,"shortGeneric"
, or"longGeneric"
.If these properties were requested in
options
, the constructor preventsdateStyle
andtimeStyle
from being specified, so the below group will never be present. dateStyle
,timeStyle
Optional-
The values provided for these properties in the
options
argument. They are either"full"
,"long"
,"medium"
,"short"
, or"none"
. Some of these properties may not be present, indicating that the corresponding components will not be represented in formatted output.If these properties were requested in
options
, the constructor prevents individual date time component options from being specified, so the above group will never be present.Note: Although
dateStyle
andtimeStyle
are shortcuts for individual date and time component styles, the exact (locale dependent) component styles they resolve to are not included in the resolved options. This ensures the result ofresolvedOptions()
can be passed directly to theIntl.DateTimeFormat()
constructor (because anoptions
object with bothdateStyle
ortimeStyle
and individual date or time component styles is not valid).
Examples
Using the resolvedOptions method
const germanFakeRegion = new Intl.DateTimeFormat("de-XX", { timeZone: "UTC" });
const usedOptions = germanFakeRegion.resolvedOptions();
usedOptions.locale; // "de" (because "de-XX" does not exist)
usedOptions.calendar; // "gregory"
usedOptions.numberingSystem; // "latn"
usedOptions.timeZone; // "UTC"
usedOptions.month; // "numeric"
Getting the user's time zone and locale preferences
The Intl.DateTimeFormat
constructor without any options uses the current system settings. You can use resolvedOptions()
to get the user's current time zone and locale's preferred calendar and numbering system:
const systemOptions = new Intl.DateTimeFormat().resolvedOptions();
systemOptions.timeZone; // e.g., "Europe/Brussels" or "Asia/Riyadh"
systemOptions.calendar; // e.g., "gregory" or "islamic-umalqura"
systemOptions.numberingSystem; // e.g., "latn" or "arab"
systemOptions.locale; // e.g., "nl-BE" or "ar-SA"
Specifications
Specification |
---|
ECMAScript Internationalization API Specification # sec-intl.datetimeformat.prototype.resolvedoptions |
Browser compatibility
BCD tables only load in the browser