Intl.RelativeTimeFormat.prototype.formatToParts()

The formatToParts() method of {{jsxref("Intl.RelativeTimeFormat")}} instances returns an array of objects representing each part of the formatted string that would be returned by {{jsxref("Intl/RelativeTimeFormat/format", "format()")}}. It is useful for building custom strings from the locale-specific tokens.

{{InteractiveExample("JavaScript Demo: Intl.RelativeTimeFormat.prototype.formatToParts()")}}

```js interactive-example const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" }); const parts = rtf.formatToParts(10, "seconds");

console.log(parts[0].value); // Expected output: "in "

console.log(parts[1].value); // Expected output: "10"

console.log(parts[2].value); // Expected output: " seconds"

## Syntax

```js-nolint
formatToParts(value, unit)

Parameters#

• value
• : Numeric value to use in the internationalized relative time message.
• unit
• : Unit to use in the relative time internationalized message. Possible values are: "year", "quarter", "month", "week", "day", "hour", "minute", "second". Plural forms are also permitted.

Return value#

An {{jsxref("Array")}} of objects containing the formatted relative time in parts. Each object has two or three properties, type, value, and optionally unit, each containing a string. The string concatenation of value, in the order provided, will result in the same string as {{jsxref("Intl/RelativeTimeFormat/format", "format()")}}. The parts can be thought of as directly obtained from calling {{jsxref("Intl/NumberFormat/formatToParts", "Intl.NumberFormat.prototype.formatToParts()")}} with the numeric value, passing only the numberingSystem option, and then adding additional type: "literal" tokens, such as "in ", " days ago", etc. All tokens that are produced by the NumberFormat have an additional unit property, which is the singular form of the input unit; this is for programmatic usage and is not localized. The localized unit is output as a part of a literal token.

When options.numeric is "auto", and there's a special string for the value, the returned array is a single literal token.

Examples#

Using formatToParts()#

const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

// Format relative time using the day unit
rtf.formatToParts(-1, "day");
// [{ type: "literal", value: "yesterday"}]

rtf.formatToParts(100, "day");
// [
//   { type: "literal", value: "in " },
//   { type: "integer", value: "100", unit: "day" },
//   { type: "literal", value: " days" }
// ]

Specifications#

{{Specifications}}

Browser compatibility#

{{Compat}}

See also#

• {{jsxref("Intl.RelativeTimeFormat")}}
• {{jsxref("Intl/RelativeTimeFormat/format", "Intl.RelativeTimeFormat.prototype.format()")}}