Intl.RelativeTimeFormat

Baseline Widely available

This feature is well established and works across many devices and browser versions. It's been available across browsers since September 2020.

The Intl.RelativeTimeFormat object enables language-sensitive relative time formatting.

Try it

const rtf1 = new Intl.RelativeTimeFormat("en", { style: "short" });

console.log(rtf1.format(3, "quarter"));
// Expected output: "in 3 qtrs."

console.log(rtf1.format(-1, "day"));
// Expected output: "1 day ago"

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

console.log(rtf2.format(2, "day"));
// Expected output: "pasado mañana"

Constructor

Intl.RelativeTimeFormat(): Creates a new Intl.RelativeTimeFormat object.

Static methods

Intl.RelativeTimeFormat.supportedLocalesOf(): Returns an array containing those of the provided locales that are supported without having to fall back to the runtime's default locale.

Instance properties

These properties are defined on Intl.RelativeTimeFormat.prototype and shared by all Intl.RelativeTimeFormat instances.

Intl.RelativeTimeFormat.prototype.constructor: The constructor function that created the instance object. For Intl.RelativeTimeFormat instances, the initial value is the Intl.RelativeTimeFormat constructor.
Intl.RelativeTimeFormat.prototype[Symbol.toStringTag]: The initial value of the [Symbol.toStringTag] property is the string "Intl.RelativeTimeFormat". This property is used in Object.prototype.toString().

Instance methods

Intl.RelativeTimeFormat.prototype.format(): Formats a value and a unit according to the locale and formatting options of the given Intl.RelativeTimeFormat object.
Intl.RelativeTimeFormat.prototype.formatToParts(): Returns an Array of objects representing the relative time format in parts that can be used for custom locale-aware formatting.
Intl.RelativeTimeFormat.prototype.resolvedOptions(): Returns a new object with properties reflecting the locale and formatting options computed during initialization of the object.

Examples

Basic format usage

The following example shows how to use a relative time formatter for the English language.

// Create a relative time formatter in your locale
// with default values explicitly passed in.
const rtf = new Intl.RelativeTimeFormat("en", {
  localeMatcher: "best fit", // other values: "lookup"
  numeric: "always", // other values: "auto"
  style: "long", // other values: "short" or "narrow"
});

// Format relative time using negative value (-1).
rtf.format(-1, "day"); // "1 day ago"

// Format relative time using positive value (1).
rtf.format(1, "day"); // "in 1 day"

Using formatToParts

The following example shows how to create a relative time formatter returning formatted parts.

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

Specification
ECMAScript® 2027 Internationalization API Specification # relativetimeformat-objects

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
`RelativeTimeFormat`	71	79	65	58	14	71	65	50	14	10.0	71	14	1.0.0	1.8	12.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. See the `RelativeTimeFormat()` constructor for more details.
`RelativeTimeFormat`	71	79	65	58	14	71	65	50	14	10.0	71	14	1.0.0	1.8	12.0.0
`format`	71	79	65	58	14	71	65	50	14	10.0	71	14	1.0.0	1.8	12.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. See the `RelativeTimeFormat()` constructor for more details.
`formatToParts`	71	79	70	58	14	71	79	50	14	10.0	71	14	1.0.0	1.8	12.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. See the `RelativeTimeFormat()` constructor for more details.
`resolvedOptions`	71	79	65	58	14	71	65	50	14	10.0	71	14	1.0.0	1.8	12.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. See the `RelativeTimeFormat()` constructor for more details.
`supportedLocalesOf`	71	79	65	58	14	71	65	50	14	10.0	71	14	1.0.0	1.8	13.0.0 12.0.0–13.0.0 Before version 13.0.0, only the locale data for `en-US` is available by default. To make full ICU (locale) data available before version 13, see Node.js documentation on the `--with-intl` option and how to provide the data.