Widely availableRecommended for localized time-relative UI, especially where terse date labels are more useful than absolute timestamps alone.
Internationalization Widely available

Intl.RelativeTimeFormat

Intl.RelativeTimeFormat formats values such as '3 days ago' or 'in 2 hours' according to locale rules. It is useful for feeds, notifications, and recent activity displays.

IntlLocalizationDates

Overview

Intl.RelativeTimeFormat formats values such as '3 days ago' or 'in 2 hours' according to locale rules. It is useful for feeds, notifications, and recent activity displays.

Browser support

Feature Desktop Mobile
Chrome
Edge
Firefox
Safari
Chrome Android
Safari iOS
javascript.builtins.Intl.RelativeTimeFormat
71
79
65
14
71
14
Built-in object
Intl.RelativeTimeFormat.RelativeTimeFormat

The Intl.RelativeTimeFormat() constructor creates Intl.RelativeTimeFormat objects.
71
79
65
14
71
14
Intl.RelativeTimeFormat.RelativeTimeFormat.locales parameter

`locales` parameter
71
79
65
14
71
14
Intl.RelativeTimeFormat.RelativeTimeFormat.options parameter.options localeMatcher parameter

`options.localeMatcher` parameter
71
79
65
14
71
14
Intl.RelativeTimeFormat.RelativeTimeFormat.options parameter.options numberingSystem parameter

`options.numberingSystem` parameter
71
79
76
14
71
14
Intl.RelativeTimeFormat.RelativeTimeFormat.options parameter.options numeric parameter

`options.numeric` parameter
71
79
65
14
71
14
Intl.RelativeTimeFormat.format

The format() method of Intl.RelativeTimeFormat instances formats a value and unit according to the locale and formatting options of this Intl.RelativeTimeFormat object.
71
79
65
14
71
14
Intl.RelativeTimeFormat.formatToParts

The formatToParts() method of Intl.RelativeTimeFormat instances returns an array of objects representing each part of the formatted string that would be returned by Intl/RelativeTimeFormat/format. It is useful for building custom strings from the locale-specific tokens.
71
79
70
14
71
14
Intl.RelativeTimeFormat.resolvedOptions

The resolvedOptions() method of Intl.RelativeTimeFormat instances returns a new object with properties reflecting the options computed during initialization of this RelativeTimeFormat object.
71
79
65
14
71
14
Intl.RelativeTimeFormat.supportedLocalesOf

The Intl.RelativeTimeFormat.supportedLocalesOf() static method returns an array containing those of the provided locales that are supported in relative time formatting without having to fall back to the runtime's default locale.
71
79
65
14
71
14
1+Supported (version) Not supported ※Has note Sub-feature descriptions sourced from MDN Web Docs (CC BY-SA 2.5)

Syntax

JAVASCRIPT 
const rtf = new Intl.RelativeTimeFormat('ja', { numeric: 'auto' });
rtf.format(-1, 'day');   // 'Yesterday'
rtf.format(2, 'hour');   // '2 hours from now'
rtf.format(-3, 'month'); // '3 months ago'

Live demo

Intl.RelativeTimeFormat

"3before""2 timebetweenafter". like relative timebetweenrepresentationationation.

PreviewFullscreen

Numeric option

Auto is "", always is "1before". like to output.

PreviewFullscreen

datetime. Display

Date and combination"Nsplitbefore". like display implementation.

PreviewFullscreen

Use cases

  • Activity feeds

    Show how recent a message, update, or upload is without forcing users to interpret a full timestamp first.

  • Status updates

    Display upcoming deadlines or elapsed time in a concise and locale-aware form.

Cautions

  • Relative times become less precise over time, so pair them with absolute timestamps when exact dates matter.
  • Auto-updating relative labels can create noisy interfaces if too many elements refresh too often.

Accessibility

  • If relative time is important, provide an absolute date as well so users are not forced to infer exact timing.

Related links

Powered by web-features