CKTIS / JavaScript
Intl.DateTimeFormat: inspect the effective options
Use `resolvedOptions()` to see which date and time formatting settings an instance actually uses instead of inferring them from the constructor arguments.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
formatter.resolvedOptions()Intl.DateTimeFormat.prototype.resolvedOptions is an instance method that takes no arguments. Each call returns a new plain object with the settings determined when the formatter was created. Editing the result does not change the formatter. Unlike format(), it takes no date and produces no formatted text. Calling it unbound or with an incompatible this such as {} throws a TypeError.
The result includes locale (the BCP 47 language tag actually selected), calendar, numberingSystem, and timeZone. It is not a copy of the constructor input: locale negotiation and defaults can change what you get. Without an explicit timeZone, the formatter uses the runtime's default zone at construction. A zone identifier can be normalized, so do not assume it matches the input string exactly.
Without dateStyle or timeStyle, properties such as year, month, and hour reflect the matched pattern; unused components are omitted. With dateStyle or timeStyle, the result reports the requested styles without expanding them into individual components. Combining a style with an explicit component option such as hour throws a TypeError in the constructor.
If the pattern includes an hour, the result has hourCycle and the derived hour12, even when timeStyle keeps the hour property out of the result. hour12 is true for h11 and h12, and false for h23 and h24. Without an hour, both properties are omitted. When choosing the cycle, the hour12 option takes precedence over hourCycle and the hc Unicode extension.
Use the result to diagnose differences between runtimes. Option support and locale data can vary, and matching resolved options do not guarantee identical formatted text.
Examples
const formatter = new Intl.DateTimeFormat("en-GB", {
timeZone: "UTC",
timeStyle: "short",
hour12: false,
});
const options = formatter.resolvedOptions();
console.log(options.timeZone);
console.log(options.timeStyle);
console.log(options.hour12);
console.log(Object.hasOwn(options, "hour"));
options.timeZone = "Asia/Tokyo";
console.log(formatter.resolvedOptions().timeZone);Result
UTC short false false UTC
The code prints `UTC`, `short`, `false`, `false`, and `UTC`, in that order. The first `false` means 24-hour time; the second means there is no own `hour` property. Assigning `Asia/Tokyo` changes only the returned object.
Related lessons
- JavaScript · Lesson 25 · Advanced · Version: 4
Sources
- ECMAScript® 2024 Internationalization API Specification — Intl.DateTimeFormat.prototype.resolvedOptions
- ECMAScript Internationalization API Specification (living draft) — Intl.DateTimeFormat.prototype.resolvedOptions
- ECMAScript Internationalization API Specification (living draft) — CreateDateTimeFormat