W3cubDocs

Intl.DateTimeFormat.prototype.formatRangeToParts()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨August 2021⁩.

The formatRangeToParts() method of Intl.DateTimeFormat instances returns an array of objects representing each part of the formatted string that would be returned by formatRange(). It is useful for building custom strings from the locale-specific tokens.

Try it

const startDate = new Date(Date.UTC(2007, 0, 10, 10, 0, 0)); // > 'Wed, 10 Jan 2007 10:00:00 GMT'
const endDate = new Date(Date.UTC(2007, 0, 10, 11, 0, 0)); // > 'Wed, 10 Jan 2007 11:00:00 GMT'

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

const parts = dateTimeFormat.formatRangeToParts(startDate, endDate);
for (const part of parts) {
  console.log(part);
}
// Expected output (in GMT timezone):
// Object { type: "hour", value: "2", source: "startRange" }
// Object { type: "literal", value: ":", source: "startRange" }
// Object { type: "minute", value: "00", source: "startRange" }
// Object { type: "literal", value: " – ", source: "shared" }
// Object { type: "hour", value: "3", source: "endRange" }
// Object { type: "literal", value: ":", source: "endRange" }
// Object { type: "minute", value: "00", source: "endRange" }
// Object { type: "literal", value: " ", source: "shared" }
// Object { type: "dayPeriod", value: "AM", source: "shared" }

Syntax

formatRangeToParts(startDate, endDate)

Parameters

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.

Return value

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".

Examples

Using formatRangeToParts()

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" },
];

Specifications

Specification
ECMAScript® 2026 Internationalization API Specification> # sec-Intl.DateTimeFormat.prototype.formatRangeToParts>

Browser compatibility

	Desktop					Mobile							Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	WebView on iOS	Bun	Deno	Node.js
`formatRangeToParts`	76	79	91	63	14.1	76	91	54	14.5	12.0	76	14.5	1.0.0	1.8	12.9.0 Before version 13.0.0, only the locale data for `en-US` is available by default. See the `DateTimeFormat()` constructor for more details.