Intl.RelativeTimeFormat

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

Constructor

Intl.RelativeTimeFormat.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 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 Status Comment
ECMAScript Internationalization API (ECMA-402)
The definition of 'RelativeTimeFormat' in that specification.

Browser compatibility

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
RelativeTimeFormatChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0
RelativeTimeFormat() constructorChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0
formatChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0
formatToPartsChrome Full support 71Edge Full support 79Firefox Full support 70IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android No support NoOpera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0
resolvedOptionsChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0
supportedLocalesOfChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari No support NoWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS No support NoSamsung Internet Android Full support 10.0nodejs Full support 12.0.0

Legend

Full support  
Full support
No support  
No support

See also