@github/time-elements
Advanced tools
Formats a timestamp as a localized string or as relative text that auto-updates in the user's browser.
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.
Available on npm as @github/time-elements.
$ npm install @github/time-elements
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.
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:
So, a relative date phrase is used for up to a month and then the actual date is shown.
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:
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>
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.
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>
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.
| 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 |
Browsers without native custom element support require a polyfill.
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.
FAQs
Formats a timestamp as a localized string or as relative text that auto-updates in the user's browser.
The npm package @github/time-elements receives a total of 0 weekly downloads. As such, @github/time-elements popularity was classified as not popular.
We found that @github/time-elements demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 20 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.