Intl.RelativeTimeFormat() constructor
=====================================

The **`Intl.RelativeTimeFormat()`** constructor creates `Intl.RelativeTimeFormat` objects.

Syntax
------


```js
new Intl.RelativeTimeFormat()
new Intl.RelativeTimeFormat(locales)
new Intl.RelativeTimeFormat(locales, options)
```


**Note:** `Intl.RelativeTimeFormat()` can only be constructed with `new`. Attempting to call it without `new` throws a `TypeError`.

### Parameters

`locales` Optional

A string with a BCP 47 language tag or an `Intl.Locale` instance, or an array of such locale identifiers. For the general form and interpretation of the `locales` argument, see the parameter description on the `Intl` main page.

The following Unicode extension key is allowed:

`nu`

See `numberingSystem`.

This key can also be set with `options` (as listed below). When both are set, the `options` property takes precedence.

`options` Optional

An object containing the following properties, in the order they are retrieved (all of them are optional):

`localeMatcher`

The locale matching algorithm to use. Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`. For information about this option, see Locale identification and negotiation.

`numberingSystem`

The numbering system to use for number formatting, such as `"arab"`, `"hans"`, `"mathsans"`, and so on. For a list of supported numbering system types, see `Intl.Locale.prototype.getNumberingSystems()`. This option can also be set through the `nu` Unicode extension key; if both are provided, this `options` property takes precedence.

`style`

The style of the formatted relative time. Possible values are:

`"long"` (default)

E.g., "in 1 month"

`"short"`

E.g., "in 1 mo."

`"narrow"`

E.g., "in 1 mo.". The narrow style could be similar to the short style for some locales.


`numeric`

Whether to use numeric values in the output. Possible values are `"always"` and `"auto"`; the default is `"always"`. When set to `"auto"`, the output may use more idiomatic phrasing such as `"yesterday"` instead of `"1 day ago"`.


### Exceptions

`RangeError`

Thrown if `locales` or `options` contain invalid values.

Examples
--------

### Basic format usage

The following example shows how to create a relative time formatter using the English language.


```js
// 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 the auto option

If `numeric:auto` option is passed, it will produce the string `yesterday` or `tomorrow` instead of `1 day ago` or `in 1 day`. This allows to not always have to use numeric values in the output.


```js
// Create a relative time formatter in your locale
// with numeric: "auto" option value passed in.
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

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

// Format relative time using positive day unit (1).
rtf.format(1, "day"); // "tomorrow"
```

Specifications
--------------

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl-relativetimeformat-constructor |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Intl.RelativeTimeFormat`
* `Intl`
* `Intl.RelativeTimeFormat` on v8.dev (2018)