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.
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
Negative means past. -3 days becomes a "ago" phrase.
Unit day. Pass the singular unit name "day".
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"));
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
Positive means future. 2 hours becomes "in 2 hours".
Default numeric. Without auto, the number always appears.
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"));
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
auto wording. English maps 0 days to "today".
Other locales. German formats -1 day as "vor 1 Tag".
Pick numeric mode. Use always when you want numbers every time.
Compatibility
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+.
ES2018Standard since
Google Chrome71+ · Desktop & Mobile
Full support
Microsoft Edge79+ · Chromium based
Full support
Mozilla Firefox65+ · Desktop & Mobile
Full support
Apple Safari14+ · macOS & iOS
Full support
Opera58+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView71+ · Chromium based
Supported
Node.js12+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
Intl.RelativeTimeFormatExcellent
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.