Creating a formatter
Introduction
Intl.RelativeTimeFormat turns a signed number and a unit into a phrase
like "3 days ago" or "in 2 weeks". This sheet covers its constructor,
options, and the usual "time ago" pattern.
Examples run on Node 26 with full ICU and an en-US default locale.
- Intl.RelativeTimeFormat on MDN (developer.mozilla.org)
- ECMA-402 specification (tc39.es)
Constructor
Syntax
new Intl.RelativeTimeFormat()
new Intl.RelativeTimeFormat(locales)
new Intl.RelativeTimeFormat(locales, options)
Formatter
const rtf = new Intl.RelativeTimeFormat('en-US')
const de = new Intl.RelativeTimeFormat('de-DE', {
numeric: 'auto'
})
locales is a BCP 47 tag or an array of tags; the first supported one wins.
Call the constructor with new — a plain call throws TypeError. Options
also accept localeMatcher (default 'best fit') and numberingSystem.
Options without a locale
Formatter
const opts = { numeric: 'auto', style: 'short' }
const rtf = new Intl.RelativeTimeFormat('default', opts)
Output
rtf.resolvedOptions().locale // → 'en-US'
Pass 'default' to mean the runtime's own locale when you still have options
to send. Leaving the argument out works the same:
new Intl.RelativeTimeFormat(undefined, opts).
See: locales argument
Formatting a value
Values and units
Formatter
const rtf = new Intl.RelativeTimeFormat('en-US')
Output
rtf.format(-1, 'day') // → '1 day ago'
rtf.format(2, 'day') // → 'in 2 days'
rtf.format(1, 'year') // → 'in 1 year'
rtf.format(-3, 'month') // → '3 months ago'
Units
| Unit | format(-1, unit) | format(2, unit) |
|---|---|---|
year | 1 year ago | in 2 years |
quarter | 1 quarter ago | in 2 quarters |
month | 1 month ago | in 2 months |
week | 1 week ago | in 2 weeks |
day | 1 day ago | in 2 days |
hour | 1 hour ago | in 2 hours |
minute | 1 minute ago | in 2 minutes |
second | 1 second ago | in 2 seconds |
Negative is the past, positive the future; zero counts as future
('in 0 days'). Unit names stay singular: 'day', never 'days'. Values
aren't rounded, so -1.5 renders as '1.5 days ago'. An unknown unit throws
RangeError.
See: format()
Numeric option
Formatter
const rtf = new Intl.RelativeTimeFormat('en-US', {
numeric: 'auto'
})
Output
rtf.format(-1, 'day') // → 'yesterday'
rtf.format(1, 'day') // → 'tomorrow'
rtf.format(0, 'day') // → 'today'
rtf.format(0, 'second') // → 'now'
rtf.format(-2, 'day') // → '2 days ago'
rtf.format(-1, 'week') // → 'last week'
'auto' uses a wording only where the locale has one for that value and
unit; 2 stays numeric. The default, 'always', prints '1 day ago' and
'in 0 days'.
See: numeric option
Style option
Formatter
const rtf = (style) => (
new Intl.RelativeTimeFormat('en-US', { style })
)
Output
rtf('short').format(-1, 'hour') // → '1 hr. ago'
rtf('narrow').format(-1, 'hour') // → '1h ago'
rtf('narrow').format(2, 'day') // → 'in 2d'
'long' is the default; 'narrow' is the most compact. numeric: 'auto'
wordings such as 'yesterday' survive both styles.
See: style option
Inspecting output
formatToParts()
Formatter
const rtf = new Intl.RelativeTimeFormat('en-US')
Output
rtf.formatToParts(-2, 'day')
// → [
// { type: 'integer', value: '2', unit: 'day' },
// { type: 'literal', value: ' days ago' }
// ]
Without a number
new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' })
.formatToParts(-1, 'day')
// → [{ type: 'literal', value: 'yesterday' }]
Parts are literal, integer, decimal or fraction. A phrase with no
number at all is a single literal part.
See: formatToParts()
resolvedOptions()
Formatter
const rtf = new Intl.RelativeTimeFormat('de-DE', {
numeric: 'auto',
style: 'short'
})
Output
rtf.resolvedOptions()
// → {
// locale: 'de-DE',
// style: 'short',
// numeric: 'auto',
// numberingSystem: 'latn'
// }
It reports the locale that matched, plus the default for every option you left out.
See: resolvedOptions()
Locales
Locale differences
Formatter
const rtf = (locale, style) => (
new Intl.RelativeTimeFormat(locale, { style })
)
Output
rtf('en-US', 'short').format(-1, 'hour') // → '1 hr. ago'
rtf('en-GB', 'short').format(-1, 'hour') // → '1 hr ago'
Long style
rtf('de-DE').format(-2, 'day') // → 'vor 2 Tagen'
rtf('ja-JP').format(-2, 'day') // → '2 日前'
You supply the number and the unit; word order, prepositions and plural
endings come from the locale data. At long style en-US and en-GB agree on
'1 day ago'; the abbreviation is where they part.
Plural forms
| Value | en-US | de-DE | ru-RU |
|---|---|---|---|
-1 | 1 day ago | vor 1 Tag | 1 день назад |
-2 | 2 days ago | vor 2 Tagen | 2 дня назад |
-5 | 5 days ago | vor 5 Tagen | 5 дней назад |
Plural selection belongs to the locale, so -1, -2 and -5 each get their
own form without extra work. ja-JP has no count agreement: 1 日前,
2 日前.
See: Intl.PluralRules
Time ago
Computing the delta
Setup
const rtf = new Intl.RelativeTimeFormat('en', {
numeric: 'auto'
})
const now = new Date('2026-11-18T12:00:00Z')
const then = new Date('2026-11-16T12:00:00Z')
Output
rtf.format((then - now) / 86_400_000, 'day')
// → '2 days ago'
The formatter never reads a clock. Subtract the dates yourself, divide down to the unit you want, and keep the sign.
See: format()
A timeAgo() helper
Helper
const rtf = new Intl.RelativeTimeFormat('en', {
numeric: 'auto'
})
const timeAgo = (date, now = Date.now()) => {
const s = Math.round((date.getTime() - now) / 1000)
if (Math.abs(s) < 60) return rtf.format(s, 'second')
if (Math.abs(s) < 3600) {
return rtf.format(Math.round(s / 60), 'minute')
}
if (Math.abs(s) < 86_400) {
return rtf.format(Math.round(s / 3600), 'hour')
}
return rtf.format(Math.round(s / 86_400), 'day')
}
Usage
const now = new Date('2026-11-18T12:00:00Z').getTime()
timeAgo(new Date('2026-11-18T11:59:30Z'), now) // '30 seconds ago'
timeAgo(new Date('2026-11-18T09:00:00Z'), now) // '3 hours ago'
timeAgo(new Date('2026-11-16T12:00:00Z'), now) // '2 days ago'
Math.round() picks a whole unit, and the sign is kept so past values stay
negative. Add month and year branches when you need coarser output.
See: Date.now()
0 Comments for this cheatsheet. Write yours!