JavaScript Intl.RelativeTimeFormat() Constructor

Beginner
5 min read
Updated: Nov 2026
3 examples
Constructor

Definition

new Intl.RelativeTimeFormat(locales, options) builds a formatter for relative time phrases. Call format(value, unit) with a number and a unit such as "day" or "hour".

Negative values point to the past ("3 days ago"). Positive values point to the future ("in 2 hours"). With numeric: "auto", some values become words like "today".

Remember
new Intl.RelativeTimeFormat(locales, options)
fmt.format(value, unit)

negative → past ("3 days ago")
positive → future ("in 2 hours")
numeric: "auto" → "today", "yesterday", ...

Syntax

Create a RelativeTimeFormat, then call format with a value and a unit.

JavaScript
const fmt = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
console.log(fmt.format(-3, "day"));
CallWhat it does
fmt.format(-3, "day")English with auto: "3 days ago".
fmt.format(2, "hour")With default numeric always: "in 2 hours".
{ numeric: "auto" }Allows words such as "today" for 0 days.
fmt.format(-1, "day")German example: "vor 1 Tag".

A standard JavaScript constructor on the Intl object: create one with new Intl.RelativeTimeFormat(). No import required. Siblings: Intl.getCanonicalLocales(), Intl.supportedValuesOf(), Intl.Collator(), Intl.DateTimeFormat(), Intl.DisplayNames(), Intl.DurationFormat(), Intl.ListFormat(), Intl.Locale(), Intl.NumberFormat(), Intl.PluralRules(), Intl.Segmenter().

Library declarations
JavaScript
// ECMAScript 2018 — Intl.RelativeTimeFormat
new Intl.RelativeTimeFormat(locales, options)
fmt.format(value, unit)

// unit: "year" | "quarter" | "month" | "week"
//     | "day" | "hour" | "minute" | "second"
// options.numeric: "always" | "auto"

Parameters

ParameterDescription
localesOptional. Locale string or list, such as "en" or "de".
optionsOptional. Commonly numeric and style.
valueFor format: how many units (negative = past).
unitFor format: singular unit name such as "day".

Return Value

Return ValueDescription
RelativeTimeFormat objectFrom the constructor.
stringFrom format: the relative time phrase.

JavaScript Examples

Example 1 — Format "3 days ago"

A negative day value formats as a past phrase in English.

JavaScript
const fmt = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

console.log(fmt.format(-3, "day"));
Try It Yourself

The Try It page first checks that Intl.RelativeTimeFormat exists, because it may be missing in older browsers. In an older browser it prints a short explanation and the output above. In current browsers it runs the code for real.

How It Works

  1. Negative means past. -3 days becomes a "ago" phrase.
  2. Unit day. Pass the singular unit name "day".
  3. auto still numeric here. Three days is far enough that English keeps the number.

Example 2 — Format "in 2 hours"

A positive hour value formats as a future phrase.

JavaScript
const fmt = new Intl.RelativeTimeFormat("en");

console.log(fmt.format(2, "hour"));
Try It Yourself

The Try It page first checks that Intl.RelativeTimeFormat exists, because it may be missing in older browsers. In an older browser it prints a short explanation and the output above. In current browsers it runs the code for real.

How It Works

  1. Positive means future. 2 hours becomes "in 2 hours".
  2. Default numeric. Without auto, the number always appears.
  3. Hour unit. Use "hour" for clock-relative phrases.

Example 3 — Use numeric auto for "today"

With numeric: "auto", zero days can become the word today. Compare with German for -1 day.

JavaScript
const en = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
const de = new Intl.RelativeTimeFormat("de");

console.log("en 0 day: " + en.format(0, "day"));
console.log("de -1 day: " + de.format(-1, "day"));
Try It Yourself

The Try It page first checks that Intl.RelativeTimeFormat exists, because it may be missing in older browsers. In an older browser it prints a short explanation and the output above. In current browsers it runs the code for real.

How It Works

  1. auto wording. English maps 0 days to "today".
  2. Other locales. German formats -1 day as "vor 1 Tag".
  3. Pick numeric mode. Use always when you want numbers every time.

Browser & Runtime Support

Intl.RelativeTimeFormat is part of ES2018. Current browsers and Node.js 12+ support it.

✓ ES2018 · Widely supported

Intl.RelativeTimeFormat

Supported in Chrome 71+, Edge 79+, Firefox 65+, Safari 14+, Opera 58+ and Node.js 12+.

ES2018 Standard since
Google Chrome 71+ · Desktop & Mobile
Full support
Microsoft Edge 79+ · Chromium based
Full support
Mozilla Firefox 65+ · Desktop & Mobile
Full support
Apple Safari 14+ · macOS & iOS
Full support
Opera 58+ · Chromium based
Full support
Samsung Internet Recent versions · Android
Supported
Android WebView 71+ · Chromium based
Supported
Node.js 12+ · Server runtime
Supported
Deno Supported · JavaScript runtime
Supported
Bun Supported · JavaScript runtime
Supported
Internet Explorer No native support
Not supported
Intl.RelativeTimeFormat Excellent

Bottom line: Safe in current browsers. Guard with typeof Intl.RelativeTimeFormat === "function" only if you still support very old engines.

Frequently Asked Questions

It formats a relative amount of time into phrases such as 3 days ago or in 2 hours.
Pass a negative value, for example format(-3, "day").
It allows special words like today or yesterday instead of always printing a number.
Singular names: year, quarter, month, week, day, hour, minute and second.
On older engines, check typeof Intl.RelativeTimeFormat === "function".

Next: Intl.Segmenter

Learn how to split text into graphemes, words and sentences.

Intl.Segmenter tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

13 people found this page helpful