Intl.RelativeTimeFormat

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

Intl.RelativeTimeFormat()

Creates a new Intl.RelativeTimeFormat object.

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.

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.

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"

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

• Intl
• The Intl.RelativeTimeFormat API
• A polyfill of Intl.RelativeTimeFormat in FormatJS