Intl.DateTimeFormat Alignment With Other Standards

Status

• Stage: 1
• Champion: Eemeli Aro
• Presentations:
  • For Stage 1 (2026.07)

Motivation

Active work is happening beyond TC39 in the web space for designing API shapes for datetime formatting. Users of the web would benefit from the same formatting options being available in HTML, JavaScript, and Unicode MessageFormat, as this would make it easier for developers to make use of them.

If the JavaScript datetime formatting API can be extended to provide a solution that also works for other parts of the web stack, the same API can be available for all users.

Prior art and other proposals

• ECMA-402 already provides two different mutually incompatible datetime formatting option styles:
  1. dateStyle and timeStyle are Style shortcuts
  2. The Date-time component options provide much more fine-grained control over individual fields.
• whatwg/html#12591 is introducing new formatting capabilities for the <time> HTML element.
• The Unicode MessageFormat standard includes draft functions for :datetime, :date, and :time formatting.

Why the current options are not sufficient

The pre-existing Intl.DateTimeFormat component options support nonsensical combinations, such as

new Intl.DateTimeFormat('en', { month: 'long', minute: 'numeric' }).format()
// "July at 36"

while its style shortcut options are not powerful enough to specify which parts of the date and time should be included in the result.

This means that as datetime formatting APIs are being developed in other spaces (such as HTML), it does not make sense for them to adopt JavaScript's current API, but to develop something new. The new options are not providing any capabilities beyond those already in ECMA-402, but are instead making a subset of them available with options that are better at guiding developers towards good internationalization practices.

Outline of a proposed solution

The Unicode MessageFormat WG spent considerable time in developing its draft solution, which is also proposed for the HTML <time> element; this should act as the starting point for the Intl.DateTimeFormat option bag design.

Its most significant features are adding the following two options:

• dateFields
  • weekday
  • day-weekday
  • month-day
  • month-day-weekday
  • year-month-day (default)
  • year-month-day-weekday
• timePrecision
  • hour
  • minute (default)
  • second

These specify the date and time fields that are included in the output, and could be combined with the pre-existing style shortcuts.

It is intentional that each of the dateFields values includes a representation of a single day, as this ensures that it can be combined with any of the timePrecision values. If additional values are to be included that do not include a day, such as year-month, we should ensure that combining such values with any time representation is treated as an error.

This work should also include the consideration of renaming at least the timeZoneName option as timeZoneStyle, to better align with other option names. Doing so would require making the old name an alias for the new one, to maintain compatibility with old code.