Intl.DateTimeFormat.prototype.formatRangeToParts()

startDate

The start of the date range. Can be a Date or Temporal.PlainDateTime object. Additionally can be a Temporal.PlainTime, Temporal.PlainDate, Temporal.PlainYearMonth, or Temporal.PlainMonthDay object if the DateTimeFormat object was configured to print at least one relevant part of the date.

Note: A Temporal.ZonedDateTime object will always throw a TypeError; use Temporal.ZonedDateTime.prototype.toLocaleString() or convert it to a Temporal.PlainDateTime object instead.

endDate

The end of the date range. Must have the same type as startDate.

An Array of objects containing the formatted date range in parts. Each object has three properties, type, value, and source, each containing a string. The string concatenation of value, in the order provided, will result in the same string as formatRange(). The type may have the same values as formatToParts(). The source can be one of the following:

startRange

The token is a part of the start date.

endRange

The token is a part of the end date.

shared

The token is shared between the start and end; for example, if the start and end dates share the same day period, that token may get reused. All literals that are part of the range pattern itself, such as the " – " separator, are also marked as shared.

If the start and end dates are equivalent at the precision of the output, then the output has the same list of tokens as calling formatToParts() on the start date, with all tokens marked as source: "shared".

The formatRange() method outputs localized, opaque strings that cannot be manipulated directly:

const date1 = new Date(Date.UTC(1906, 0, 10, 10, 0, 0)); // Wed, 10 Jan 1906 10:00:00 GMT
const date2 = new Date(Date.UTC(1906, 0, 10, 11, 0, 0)); // Wed, 10 Jan 1906 11:00:00 GMT

const fmt = new Intl.DateTimeFormat("en", {
  hour: "numeric",
  minute: "numeric",
});

console.log(fmt.formatRange(date1, date2)); // '10:00 – 11:00 AM'

However, in many user interfaces you may want to customize the formatting of this string, or interleave it with other texts. The formatRangeToParts() method produces the same information in parts:

console.log(fmt.formatRangeToParts(date1, date2));

// return value:
[
  { type: "hour", value: "10", source: "startRange" },
  { type: "literal", value: ":", source: "startRange" },
  { type: "minute", value: "00", source: "startRange" },
  { type: "literal", value: " – ", source: "shared" },
  { type: "hour", value: "11", source: "endRange" },
  { type: "literal", value: ":", source: "endRange" },
  { type: "minute", value: "00", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "dayPeriod", value: "AM", source: "shared" },
];

• Intl.DateTimeFormat
• Intl.DateTimeFormat.prototype.formatRange()