Intl.
Formats relative time in the chosen language, e.g. "in 3 days", "2 hours ago", or "yesterday".
- Returns
- A formatter object with
format()andformatToParts()methods.
Example
#const rtf = new Intl.RelativeTimeFormat('en-US')
console.log(rtf.format(-1, 'day'))
console.log(rtf.format(3, 'day'))
console.log(rtf.format(-2, 'hour'))
console.log(rtf.format(-5, 'minute'))Definition and usage
#Intl.RelativeTimeFormat turns a number and a time unit into a natural description. format(-2, "hour") gives "2 hours ago", and format(3, "day") gives "in 3 days". A negative number means the past, a positive one the future. The formatter picks the correct word forms for the given language on its own.
The available units are "second", "minute", "hour", "day", "week", "month", "quarter", and "year". The numeric: "auto" option uses words instead of numbers where the language has them: "yesterday", "today", "tomorrow", "next week". The style option, with the values "long", "short", and "narrow", shortens the text, e.g. to "in 3 hr.".
The formatter doesn’t calculate the difference between dates. You compute how many seconds, minutes, or days have passed, and choose the unit yourself. A short function usually does this, checking the size of the difference and picking the largest sensible unit, as in the time-since-publication example below.
Syntax
#new Intl.RelativeTimeFormat(locales)
new Intl.RelativeTimeFormat(locales, options)
formatter.format(value, unit)Parameters
#locales
optional, string or array
A locale code, e.g."en-US"or"pl-PL". If omitted, it means the browser’s language.options
optional object
Settings:numeric("always"or"auto") andstyle("long","short", or"narrow").
More examples
#const rtf = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' })
for (const days of [-2, -1, 0, 1, 2]) {
console.log(rtf.format(days, 'day'))
}
console.log(rtf.format(1, 'week'))
console.log(rtf.format(-3, 'day'))English only has special words for yesterday, today, and tomorrow. Two days or more in either direction, and the formatter falls back to the numeric form.
const rtf = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' })
function timeAgo(date, now) {
const seconds = Math.round((date - now) / 1000)
const units = [
['day', 86400],
['hour', 3600],
['minute', 60]
]
for (const [unit, size] of units) {
if (Math.abs(seconds) >= size) {
return rtf.format(Math.round(seconds / size), unit)
}
}
return rtf.format(seconds, 'second')
}
const now = new Date('2026-09-29T12:00:00Z')
console.log(timeAgo(new Date('2026-09-29T11:15:00Z'), now))
console.log(timeAgo(new Date('2026-09-29T07:00:00Z'), now))
console.log(timeAgo(new Date('2026-09-28T09:00:00Z'), now))
console.log(timeAgo(new Date('2026-09-29T11:59:50Z'), now))const short = new Intl.RelativeTimeFormat('en-US', { style: 'short' })
const pl = new Intl.RelativeTimeFormat('pl-PL', { numeric: 'auto' })
console.log(short.format(3, 'hour'))
console.log(short.format(-2, 'month'))
console.log(pl.format(-1, 'day'))
console.log(pl.format(2, 'week'))Browser support
#Widely available · since 2020
Works in all modern browsers, phones included. You can use it without worry.
- Chrome
- Edge
- Firefox
- Safari
Good practices
#- Turn on
numeric: "auto"to show the natural "yesterday" instead of "1 day ago", and "tomorrow" instead of "in 1 day". - Watch the sign of the number: a negative value is the past ("ago"), a positive value is the future ("in"). Subtracting dates in the wrong order is the most common mistake.
- For exact deadlines, like a project due date, use
Intl.DateTimeFormat. Relative time works best for fresh events: notifications, comments, and friends’ activity.
Related entries
#- Intl.DateTimeFormatFormats dates and times according to the rules of a chosen language and time zone.
- DateAn object representing a specific moment in time, with methods to read and change the date and time.
- Intl.PluralRulesPicks the correct grammatical category for a number in a given language, such as one, few, or many.
- Intl.NumberFormatFormats numbers according to a given language’s rules: separators, currencies, percentages, and units.
Spotted a mistake or missing an example? Write to us.