Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Date and Intl

The Intl.RelativeTimeFormat object

Reference for Intl.RelativeTimeFormat: write phrases like 'yesterday' or '3 hours ago' in any language, with numeric auto, styles and formatToParts().

Intl.RelativeTimeFormat produces phrases such as "in 3 days", "2 months ago" or "yesterday" in the language you choose. You give it a number and a unit; it handles the grammar, including plural forms and word order, which differ a lot between languages.

It does not calculate the difference between two dates for you. You work out the number and the unit yourself, then let the formatter write the sentence. Negative numbers mean the past, positive numbers the future.

JavaScript
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
rtf.format(-1, "day"); // "yesterday"
rtf.format(3, "week"); // "in 3 weeks"

Try it

JS Numbers and words

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Other languages and styles

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
new Intl.RelativeTimeFormat()
new Intl.RelativeTimeFormat(locales)
new Intl.RelativeTimeFormat(locales, options)

formatter.format(value, unit)
formatter.formatToParts(value, unit)
formatter.resolvedOptions()
Name Description
locales A language tag, an array of tags, or undefined for the default locale.
options.numeric "always" (default) always uses a number: "1 day ago". "auto" uses words when the language has them: "yesterday", "tomorrow", "today".
options.style "long" (default), "short" or "narrow".
value A finite number. Negative is the past, positive the future. Fractions are allowed.
unit "second", "minute", "hour", "day", "week", "month", "quarter" or "year". The plural forms ("days") are accepted too.

Return value: a string from format(); an array of { type, value, unit? } objects from formatToParts().

Exceptions: a RangeError is thrown for an unsupported unit or a non-finite value such as Infinity or NaN, and for an invalid locale tag.

Usage notes

  • Sign is direction. -2 means two units ago, 2 means in two units. Passing the wrong sign gives a sentence that is grammatical but wrong.
  • numeric: "auto" only changes some values. In English it affects -1, 0 and 1 for days, years, weeks and so on; other values still use numbers.
  • Zero: format(0, "day") gives "in 0 days" with "always" and "today" with "auto". The sign of zero matters in some locales, and -0 reads as past.
  • You choose the unit. The formatter never picks "hours" or "days" automatically; write a helper like the one above, or compare timestamps yourself.
  • Rounding is yours. Math.round(), Math.floor() or Math.trunc() give different wording near boundaries, so pick one and keep it consistent.
  • Large numbers get separators: 1000 seconds is written "in 1,000 seconds" in English.
  • Pair it with a Date fallback. After a few weeks, "47 days ago" is less useful than a real date from Intl.DateTimeFormat.
  • Re-render over time. Text such as "5 minutes ago" goes stale; update it on a timer if the page stays open.

Browser support

Supported in all current browsers and in Node.js. Check a compatibility table if you must support very old browsers.