Repository files navigation

Formats a timestamp as a localized string or as relative text that auto-updatesin the user's browser.

This allows the server to cache HTML fragments containing dates and lets thebrowser choose how to localize the displayed time according to the user'spreferences. For example, the server may have cached the following generatedmarkup:

<relative-timedatetime="2014-04-01T16:30:00-08:00"> April 1, 2014 4:30pm</relative-time>

Every visitor is served the same markup from the server's cache. When it reachesthe browser, the customrelative-time JavaScript localizes the element's textinto the local timezone and formatting.

<relative-timedatetime="2014-04-01T16:30:00-08:00"> 1 Apr 2014 21:30</relative-time>

Dates are displayed before months, and a 24-hour clock is used, according to theuser's browser settings.

If the browser's JavaScript is disabled, the default text served in the cachedmarkup is still displayed.

Available onnpm as@github/relative-time-element.

npm install @github/relative-time-element

This element uses theIntl.DateTimeFormat &Intl.RelativeTimeFormat APIs,which are supported by all modern JS engines. If you need to support an olderbrowser, you may need to introduce a polyfill forIntl.DateTimeFormat &Intl.RelativeTimeFormat.

Add a<relative-time> element to your markup. Provide a default formatted dateas the element's text content (e.g. April 1, 2014). It also MUST have adatetime attribute set to an ISO 8601 formatted timestamp.

<relative-timedatetime="2014-04-01T16:30:00-08:00"> April 1, 2014</relative-time>

Depending on how far in the future this is being viewed, the element's text willbe replaced with one of the following formats:

• 6 years from now
• 20 days from now
• 4 hours from now
• 7 minutes from now
• just now
• 30 seconds ago
• a minute ago
• 30 minutes ago
• an hour ago
• 20 hours ago
• a day ago
• 20 days ago
• on Apr 1, 2014

So, a relative date phrase is used for up to a month and then the actual date isshown.

^*: If unspecified,formatStyle will'short' if the format is'relative' or'datetime', otherwise it will be'long'.

^**: If unspecified,month will return the same value asformatStyle wheneverformat is'datetime', otherwise it will be'short'.

^***: If unspecified,weekday will return the same value asformatStyle wheneverformat is'datetime', otherwise it will beundefined.

^****: If unspecified,year will return'numeric' ifdatetime represents the same year as the current year. It will returnundefined if unspecified and ifdatetime represents a different year to thecurrent year.

This is the datetime that the element is meant to represent. This must be avalidISO8601 DateTime. It is alsopossible to use thedate property on the element to set the date.el.dateexpects aDate object, whileel.datetime expects a string. Setting one willoverride the other.

<relative-timedatetime="2014-04-01T16:30:00-08:00"tense="past">  April 1, 2038<!-- Will display "now" until April 1 2038 at 16:30:01! --></relative-time><script>constel=document.querySelector('relative-time')console.assert(el.date.toISOString()===el.datetime)el.date=newDate()console.assert(el.datetime!=='2014-04-01T16:30:00-08:00')</script>

Format can be either'datetime','relative', or'duration'. The defaultformat isrelative.relative.

Thedatetime format will display a localised datetime, based on the otherproperties of the element. It usesIntl.DateTimeFormat to display thedatetime in a localised format.

Unless specified, it will considerweekday to be'long',month to be'long', and'year' to benumeric if thedatetime is the same as thegiven year. OverridingformatStyle will change bothweekday andmonthdefault values. Examples of this format with the default options and anenlocale:

• Wed, 26 Aug 2021
• Sat, 31 Dec (assuming thedatetime is same year as the current year)

The defaultrelative format will display dates relative to the current time(unless they are past thethreshold value - see below). The values are roundedto display a single unit, for example if the time between the givendatetimeand the current wall clock time exceeds a day, then the format willonly ouputin days, and will not display hours, minutes or seconds. Some examples of thisformat with the default options and anen locale:

• in 20 days
• 20 days ago
• in 1 minute
• on 31 Aug (assuming the current date is the same year as the current year,and is more than 30 days away from 31 Aug)
• on 26 Aug 2021 (assuming the current date is more than 30 days away from 26Aug 2021)

Theduration format will display the time remaining (or elapsed time) from thegiven datetime, counting down the number of years, months, weeks, days, hours,minutes, and seconds. Any value that is0 will be omitted from the display bydefault. Examples of this format with the default options and anen locale:

• 4 hours, 2 minutes, 30 seconds
• 4 hours
• 8 days, 30 minutes, 1 second

Ifformat is'datetime' then this value will be ignored.

Tense can be used to preventduration orrelative formatted dates displayingdates in a tense other than the one specified. Settingtense=past will alwaysdisplay futurerelative dates asnow andduration dates as0 seconds,while setting it tofuture will always display past datesrelative asnowand pastduration dates as0 seconds.

For example when the givendatetime is 40 seconds behind of the current date:

<relative-timedatetime="2038-04-01T16:30:00-08:00"tense="past">  April 1, 2038<!-- Will display "now" until April 1 2038 at 16:30:01! --></relative-time>

<relative-timedatetime="1970-04-01T16:30:00-08:00"tense="future">  April 1, 2038<!-- Will display "now" unless you had a time machine and went back to 1970 --></relative-time>

Ifformat isdatetime then this value will be ignored.

Precision can be used to limit the display of anrelative ordurationformatted time. By default times will display down to thesecond level ofprecision. Changing this value will truncate the display by zeroing out any unitlower than the given unit, as such units smaller than the given unit won't bedisplayed duringduration, andrelative will displaynow if the time awayfrom the current time is less than the given precision unit.

Iftense is anything other than'auto', orformat is'relative', thenthis value will be ignored.

Threshold can be used to specify when a relative display (e.g. "5 days ago")should turn into an absolute display (i.e. the full date). This should be avalidISO8601 Time Duration.If the difference between the current time and the specifieddatetime ismore than the duration, then the date will be displayed as an absolute value(i.e. the full date), otherwise it will be formatted to a relative display (e.g."5 days ago").

The default value for this isP30D, meaning if the current time is more than30 days away from the specified date time, then an absolute date will bedisplayed.

<relative-timedatetime="1970-04-01T16:30:00-08:00"threshold="P100Y"><!-- Will display "<N> years ago" until 2070 when it will display "on April 1, 1970" --></relative-time>

<relative-timedatetime="1970-04-01T16:30:00-08:00"threshold="P0S"><!-- Will always display "on April 1, 1970" --></relative-time>

Iftense is anything other than'auto', orformat is anything other than'relative', then this value will be ignored.

When formatting an absolute date (see abovethreshold for more details) it canbe useful to prefix the date with some text. The default value for this isonbut it can be any string value, an will be prepended to the date.

<relative-timedatetime="1970-04-01T16:30:00-08:00"prefix="this happened on"><!-- Will always display "this happened on April 1, 1970" --></relative-time>

This will used to determine the length of the unit names. This value is passedto theIntl objects as thestyle option. Some examples of how this can beused:

For dates outside of the specifiedthreshold, the formatting of the date canbe configured using these attributes. The values for these attributes are passedtoIntl.DateTimeFormat:

Lang is abuilt-in global attribute.Relative Time will use this to provide an applicable language to theIntlAPIs. If the individual element does not have alang attribute then it willtraverse upwards in the tree to find the closest element that does, or defaultthe lang toen.

Browsers without native [custom element support][support] require a[polyfill][ce-polyfill].

Browsers without native support forIntl.RelativeTimeFormat orIntl.DateTimeFormat (such as Safari 13 or Edge 18) will alsoneed polyfills.

• Chrome
• Firefox
• Safari (version 14 and above)
• Microsoft Edge (version 79 and above)

Most of this implementation is based on Basecamp'slocal_time component. Thanks to @javanfor open sourcing that work and allowing for others to build on top of it.

@rmm5t'sjquery-timeago is one of theold time-ago-in-words JS plugins.