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
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 theIntl.RelativeTimeFormat
constructor. Intl.RelativeTimeFormat.prototype[Symbol.toStringTag]
-
The initial value of the
[Symbol.toStringTag]
property is the string"Intl.RelativeTimeFormat"
. This property is used inObject.prototype.toString()
.
Instance methods
Intl.RelativeTimeFormat.prototype.format()
-
Formats a
value
and aunit
according to the locale and formatting options of the givenIntl.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 Internationalization API Specification # relativetimeformat-objects |
Browser compatibility
BCD tables only load in the browser
See also
- Polyfill of
Intl.RelativeTimeFormat
in FormatJS Intl
Intl.RelativeTimeFormat
on v8.dev (2018)