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.
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" }); rtf.format(-1, "day"); // "yesterday" rtf.format(3, "week"); // "in 3 weeks"
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
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.
-2means two units ago,2means 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,0and1for 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-0reads 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()orMath.trunc()give different wording near boundaries, so pick one and keep it consistent. - Large numbers get separators:
1000seconds is written "in 1,000 seconds" in English. - Pair it with a
Datefallback. After a few weeks, "47 days ago" is less useful than a real date fromIntl.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.