Relative Time Formatting with Intl.RelativeTimeFormat

Intl.RelativeTimeFormat: Human-Readable Time Differences

Intl.RelativeTimeFormat produces locale-sensitive relative time phrases like "3 days ago", "in 2 hours", or "yesterday".

Basic Usage

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'always' });

rtf.format(-1, 'day');    // "1 day ago"
rtf.format(-3, 'day');    // "3 days ago"
rtf.format(2, 'hour');    // "in 2 hours"
rtf.format(-1, 'month');  // "1 month ago"

Numeric vs Auto Mode

const always = new Intl.RelativeTimeFormat('en', { numeric: 'always' });
const auto = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

always.format(-1, 'day');  // "1 day ago"
auto.format(-1, 'day');    // "yesterday"

always.format(0, 'day');   // "in 0 days"
auto.format(0, 'day');     // "today"

always.format(1, 'day');   // "in 1 day"
auto.format(1, 'day');     // "tomorrow"

The auto mode uses special words like "yesterday", "today", "tomorrow", "last week", "next year" when available.

Style Options

// "long" (default): "3 days ago"
// "short":          "3 days ago" (often same as long in English)
// "narrow":         "3d ago"

Across Locales

new Intl.RelativeTimeFormat('ja', { numeric: 'auto' })
  .format(-1, 'day');  // "昨日"

new Intl.RelativeTimeFormat('de', { numeric: 'auto' })
  .format(-1, 'day');  // "gestern"

new Intl.RelativeTimeFormat('fr', { numeric: 'auto' })
  .format(1, 'week');  // "la semaine prochaine"

new Intl.RelativeTimeFormat('ko', { numeric: 'auto' })
  .format(-1, 'day');  // "어제"

Supported Units

year, quarter, month, week, day, hour, minute, second

Important Limitation

Intl.RelativeTimeFormat does NOT calculate the time difference. You must compute the numeric value yourself:

const diff = targetDate - Date.now();
const days = Math.round(diff / (1000 * 60 * 60 * 24));
rtf.format(days, 'day');