<relative-time> element

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

This allows the server to cache HTML fragments containing dates and lets the browser choose how to localize the displayed time according to the user's preferences. For example, the server may have cached the following generated markup:

<relative-time datetime="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 reaches the browser, the custom relative-time JavaScript localizes the element's text into the local timezone and formatting.

<relative-time datetime="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 the user's browser settings.

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

Installation

Available on npm as @github/relative-time-element.

npm install @github/relative-time-element

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

Usage

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

<relative-time datetime="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 will be replaced with one of the following formats:

• 6 years from now
• 20 days from now
• 4 hours from now
• 7 minutes from now
• 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 is shown.

Attributes

Property Name	Attribute Name	Possible Values	Default Value
datetime	datetime	string	-
format	format	'datetime'\|'relative'\|'duration'	'auto'
date	-	Date \| null	-
tense	tense	'auto'\|'past'\|'future'	'auto'
precision	precision	'year'\|'month'\|'day'\|'hour'\|'minute'\|'second'	'second'
threshold	threshold	string	'P30D'
prefix	prefix	string	'on'
formatStyle	format-style	'long'\|'short'\|'narrow'	*
second	second	'numeric'\|'2-digit'\|undefined	undefined
minute	minute	'numeric'\|'2-digit'\|undefined	undefined
hour	hour	'numeric'\|'2-digit'\|undefined	undefined
weekday	weekday	'short'\|'long'\|'narrow'\|undefined	**
day	day	'numeric'\|'2-digit'\|undefined	'numeric'
month	month	'numeric'\|'2-digit'\|'short'\|'long'\|'narrow'\|undefined	***
year	year	'numeric'\|'2-digit'\|undefined	****
timeZoneName	time-zone-name	'long'\|'short'\|'shortOffset'\|'longOffset' \|'shortGeneric'\|'longGeneric'\|undefined	undefined
timeZone	time-zone	string\|undefined	Browser default time zone
hourCycle	hour-cycle	'h11'\|'h12'\|'h23'\|'h24'\|undefined	'h12' or 'h23' based on browser
noTitle	no-title	-	-

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

^**: If unspecified, month will return the same value as formatStyle whenever format is 'datetime', otherwise it will be 'short'.

^***: If unspecified, weekday will return the same value as formatStyle whenever format is 'datetime', otherwise it will be undefined.

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

datetime (string)

This is the datetime that the element is meant to represent. This must be a valid ISO8601 DateTime. It is also possible to use the date property on the element to set the date. el.date expects a Date object, while el.datetime expects a string. Setting one will override the other.

<relative-time datetime="2014-04-01T16:30:00-08:00" tense="past">
  April 1, 2038

</relative-time>
<script>
  const el = document.querySelector('relative-time')
  console.assert(el.date.toISOString() === el.datetime)
  el.date = new Date()
  console.assert(el.datetime !== '2014-04-01T16:30:00-08:00')
</script>

format ('datetime'|'relative'|'duration'|'auto'|'micro'|'elapsed')

Format can be either 'datetime', 'relative', or 'duration'. It can also be one of several deprecated formats of 'auto', 'micro', or 'elapsed'.

The default format is auto, which is an alias for relative. In the next major version this will be relative.

format=datetime

The datetime format will display a localised datetime, based on the other properties of the element. It uses Intl.DateTimeFormat to display the datetime in a localised format.

Unless specified, it will consider weekday to be 'long', month to be 'long', and 'year' to be numeric if the datetime is the same as the given year. Overriding formatStyle will change both weekday and month default values. Examples of this format with the default options and an en locale:

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

format=relative

The default relative format will display dates relative to the current time (unless they are past the threshold value - see below). The values are rounded to display a single unit, for example if the time between the given datetime and the current wall clock time exceeds a day, then the format will only output in days, and will not display hours, minutes or seconds. Some examples of this format with the default options and an en 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 26 Aug 2021)

format=duration

The duration format will display the time remaining (or elapsed time) from the given datetime, counting down the number of years, months, weeks, days, hours, minutes, and seconds. Any value that is 0 will be omitted from the display by default. Examples of this format with the default options and an en locale:

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

time-zone (string)

Thetime-zone attribute allows you to specify the IANA time zone name (e.g., America/New_York, Europe/London) used for formatting the date and time.

You can set the time zone either as an attribute or property:

<relative-time datetime="2024-06-01T12:00:00Z" ... time-zone="America/New_York">
  June 1, 2024 8:00am EDT
</relative-time>

If the individual element does not have a time-zone attribute then it will traverse upwards in the tree to find the closest element that does, or default the time-zone to the browsers default.

Deprecated Formats

format=elapsed

This is similar to the format=duration, except the formatStyle defaults to narrow. Code that uses format=elapsed should migrate to format=duration formatStyle=narrow, as it will be removed in a later version.

format=auto

This is identical to format=relative. Code that uses format=auto should migrate to format=relative as this will be the new default in a later version.

format=micro

The micro format displays relative dates in a more compact format. Similar to relative, the micro format rounds values to the nearest largest value. Additionally, micro format will not round lower than 1 minute, as such a datetime which is less than a minute from the current wall clock time will display '1m'.

If the threshold attribute is explicitly set, micro will display compact relative dates within the threshold and absolute dates outside of it. If threshold is not set, micro will continue to display compact relative dates without applying the default threshold.

When tense is set to past or future, micro uses Intl.RelativeTimeFormat with style: 'narrow' to include localized tense phrasing such as 2w ago or in 3d. With the default tense=auto, micro preserves the compact duration output such as 2w.

Code that uses format=micro should consider migrating to format=relative (perhaps with formatStyle=narrow), as format=micro can be difficult for users to understand, and can cause issues with assistive technologies. For example some screen readers (such as VoiceOver for mac) will read out 1m as 1 meter.

Cheatsheet

format=datetime	format=relative	format=duration	format=micro	format=elapsed
Wed 26 May 2024	in 2 years	2 years, 10 days, 3 hours, 20 minutes, 8 seconds	2y	2y 10d 3h 20m 8s
Wed 26 Aug 2021	2 years ago	2 years, 10 days, 3 hours, 8 seconds	2y	2y 10d 3h 8s
Jan 15 2023	in 30 days	30 days, 4 hours, 20 minutes, 8 seconds	30d	30d 4h 20m 8s
Dec 15 2022	21 minutes ago	21 minutes, 30 seconds	21m	21m 30s
Dec 15 2022	37 seconds ago	37 seconds	1m	37s

tense ('auto'|'past'|'future', default: auto)

If format is 'datetime' then this value will be ignored.

Tense can be used to prevent duration or relative formatted dates displaying dates in a tense other than the one specified. Setting tense=past will always display future relative dates as now and duration dates as 0 seconds, while setting it to future will always display past dates relative as now and past duration dates as 0 seconds. For format=micro, tense=past and tense=future add localized compact tense phrasing.

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

tense=	format=duration	format=relative	format=micro
future	0s	now	in 1m
past	40s	40s ago	1m ago
auto	40s	40s ago	1m

<relative-time datetime="2038-04-01T16:30:00-08:00" tense="past">
  April 1, 2038

</relative-time>

<relative-time datetime="1970-04-01T16:30:00-08:00" tense="future">
  April 1, 2038

</relative-time>

precision ('year'|'month'|'day'|'hour'|'minute'|'second', default: 'second')

If format is datetime then this value will be ig