Skip to content

Releases: github/relative-time-element

v3.0.7

12 Sep 10:57
Compare
Choose a tag to compare
  • types(TS): add window declarations e6a89ca
  • repaired example ed0209e
  • Bump eslint-utils from 1.3.1 to 1.4.2 0cd2ea0

v3.0.6...v3.0.7

v3.0.6

14 Aug 12:25
67c97d2
Compare
Choose a tag to compare
  • Merge pull request #118 from github/add-typescript-definition-file cbb381a
  • Merge branch 'master' into add-typescript-definition-file 743a66a
  • Merge branch 'master' into add-typescript-definition-file a9cab58
  • change getter to a readonly property d246182
  • add missing declare keyword 5358d12
  • add typescript definition file 6fd7791
  • only ship dist/ folder in package d3d5f59

v3.0.5...v3.0.6

3.0.6

14 Aug 12:25
cbb381a
Compare
Choose a tag to compare

<time> element extensions

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:

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

Every visitor is served the same markup from the server's cache. When it reaches the browser, the custom local-time JavaScript localizes the element's text into the local timezone and formatting.

<local-time datetime="2014-04-01T16:30:00-08:00">
  1 Apr 2014 21:30
</local-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/time-elements.

$ npm install @github/time-elements

Usage

This component provides three custom subtypes of the standard HTML <time> element. All custom time elements MUST have a datetime attribute set to an ISO 8601 formatted timestamp.

relative-time

A relative time-ago-in-words description can be generated by using the relative-time element extension.

Add a <relative-time> element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2014).

<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
  • 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 is shown.

time-until

You can use time-until to always display a relative date that's in the future. It operates much like <relative-time>, except in the reverse, with past events shown as just now and future events always showing as relative:

  • 10 years from now
  • 20 days from now
  • 6 hours from now
  • 20 minutes from now
  • 30 seconds from now
  • just now

Add a <time-until> element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2024).

<time-until datetime="2024-04-01T16:30:00-08:00">
  April 1, 2024
</time-until>

time-ago

An always relative time-ago-in-words description can be generated by using the time-ago element extension. This is similar to the relative-time extension. However, this will never switch to displaying the date. It strictly shows relative date phrases, even after a month has passed.

<time-ago datetime="2012-04-01T16:30:00-08:00">
  April 1, 2014
</time-ago>

For example, if this markup is viewed two years in the future, the element's text will read 2 years ago.

Micro format

The optional format="micro" attribute shortens the descriptions to 1m, 1h, 1d, 1y.

<time-ago datetime="2012-04-01T16:30:00-08:00" format="micro">
  April 1, 2014
</time-ago>

local-time

This custom time extension is useful for formatting a date and time in the user's preferred locale format.

<local-time datetime="2014-04-01T16:30:00-08:00"
    month="short"
    day="numeric"
    year="numeric"
    hour="numeric"
    minute="numeric">
  April 1, 2014 4:30PM PDT
</local-time>

When this markup is viewed in a CDT timezone, it will show Apr 1, 2014 6:30PM. If it's viewed in a browser with European date preferences, it will read 1 Apr 2014 18:30.

Options

Attribute Options Description
datetime ISO 8601 date Required date of element 2014-06-01T13:05:07Z
year 2-digit, numeric Format year as 14 or 2014
month short, long Format month as Jun or June
day 2-digit, numeric Format day as 01 or 1
weekday short, long Format weekday as Sun or Sunday
hour 2-digit, numeric Format hour as 01 or 1
minute 2-digit, numeric Format minute as 05 or 5
second 2-digit, numeric Format second as 07 or 7
time-zone-name short, long Display time zone as GMT+1 or by its full name

Browser Support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

See Also

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

@rmm5t's jquery-timeago is one of the old time-ago-in-words JS plugins.

v3.0.5

06 Aug 14:34
1a9c306
Compare
Choose a tag to compare
  • Merge pull request #121 from github/publish-to-gpr-as-well 014b256
  • publish to GPR as a postpublish step f5fd0ae

v3.0.4...v3.0.5

3.0.5

06 Aug 14:34
014b256
Compare
Choose a tag to compare

<time> element extensions

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:

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

Every visitor is served the same markup from the server's cache. When it reaches the browser, the custom local-time JavaScript localizes the element's text into the local timezone and formatting.

<local-time datetime="2014-04-01T16:30:00-08:00">
  1 Apr 2014 21:30
</local-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/time-elements.

$ npm install @github/time-elements

Usage

This component provides three custom subtypes of the standard HTML <time> element. All custom time elements MUST have a datetime attribute set to an ISO 8601 formatted timestamp.

relative-time

A relative time-ago-in-words description can be generated by using the relative-time element extension.

Add a <relative-time> element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2014).

<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
  • 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 is shown.

time-until

You can use time-until to always display a relative date that's in the future. It operates much like <relative-time>, except in the reverse, with past events shown as just now and future events always showing as relative:

  • 10 years from now
  • 20 days from now
  • 6 hours from now
  • 20 minutes from now
  • 30 seconds from now
  • just now

Add a <time-until> element to your markup. Provide a default formatted date as the element's text content (e.g. April 1, 2024).

<time-until datetime="2024-04-01T16:30:00-08:00">
  April 1, 2024
</time-until>

time-ago

An always relative time-ago-in-words description can be generated by using the time-ago element extension. This is similar to the relative-time extension. However, this will never switch to displaying the date. It strictly shows relative date phrases, even after a month has passed.

<time-ago datetime="2012-04-01T16:30:00-08:00">
  April 1, 2014
</time-ago>

For example, if this markup is viewed two years in the future, the element's text will read 2 years ago.

Micro format

The optional format="micro" attribute shortens the descriptions to 1m, 1h, 1d, 1y.

<time-ago datetime="2012-04-01T16:30:00-08:00" format="micro">
  April 1, 2014
</time-ago>

local-time

This custom time extension is useful for formatting a date and time in the user's preferred locale format.

<local-time datetime="2014-04-01T16:30:00-08:00"
    month="short"
    day="numeric"
    year="numeric"
    hour="numeric"
    minute="numeric">
  April 1, 2014 4:30PM PDT
</local-time>

When this markup is viewed in a CDT timezone, it will show Apr 1, 2014 6:30PM. If it's viewed in a browser with European date preferences, it will read 1 Apr 2014 18:30.

Options

Attribute Options Description
datetime ISO 8601 date Required date of element 2014-06-01T13:05:07Z
year 2-digit, numeric Format year as 14 or 2014
month short, long Format month as Jun or June
day 2-digit, numeric Format day as 01 or 1
weekday short, long Format weekday as Sun or Sunday
hour 2-digit, numeric Format hour as 01 or 1
minute 2-digit, numeric Format minute as 05 or 5
second 2-digit, numeric Format second as 07 or 7
time-zone-name short, long Display time zone as GMT+1 or by its full name

Browser Support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

See Also

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

@rmm5t's jquery-timeago is one of the old time-ago-in-words JS plugins.

v3.0.4

31 Jul 16:26
77a086c
Compare
Choose a tag to compare
  • Merge pull request #119 from github/dependabot/npm_and_yarn/lodash-4.17.15 0f82334
  • Bump lodash from 4.17.11 to 4.17.15 f316af6

v3.0.3...v3.0.4

v3.0.3

22 Jul 12:38
b1e18b0
Compare
Choose a tag to compare
  • Merge pull request #117 from github/update-deps 565c156
  • update eslint, eslint-plugin-github and flow-bin manually to latest versions 2946d98
  • run npm update f85ebd8

v3.0.2...v3.0.3

v3.0.2

13 Jun 12:13
daa40b1
Compare
Choose a tag to compare
  • Merge pull request #116 from github/add-missing-scope-to-readme-and-flow-files 8aa8933
  • fix whitespace d478a24
  • fix flow annotation comment eed4469
  • add missing @github scope to README and flow files f5cb054

v3.0.1...v3.0.2

v3.0.0

13 Jun 08:45
2c6fabd
Compare
Choose a tag to compare

Same as beta-4, just now not in beta anymore! ✨

v3.0.0-beta.2

05 Jun 12:19
7d8ce76
Compare
Choose a tag to compare
v3.0.0-beta.2 Pre-release
Pre-release
  • make sure to format months ago d307508

v3.0.0-beta.1...v3.0.0-beta.2