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.

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.

See: Intl.RelativeTimeFormat() constructor

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

Unitformat(-1, unit)format(2, unit)
year1 year agoin 2 years
quarter1 quarter agoin 2 quarters
month1 month agoin 2 months
week1 week agoin 2 weeks
day1 day agoin 2 days
hour1 hour agoin 2 hours
minute1 minute agoin 2 minutes
second1 second agoin 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.

See: ECMA-402 RelativeTimeFormat objects

Plural forms

Valueen-USde-DEru-RU
-11 day agovor 1 Tag1 день назад
-22 days agovor 2 Tagen2 дня назад
-55 days agovor 5 Tagen5 дней назад

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!