https://github.com/rbardini/time-duration
⏱️ A web component to format <time> elements with the elapsed time.
https://github.com/rbardini/time-duration
duration elapsed temporal time web-component
Last synced: 5 months ago
JSON representation
⏱️ A web component to format <time> elements with the elapsed time.
- Host: GitHub
- URL: https://github.com/rbardini/time-duration
- Owner: rbardini
- License: mit
- Created: 2024-10-06T00:36:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-06T01:18:50.000Z (over 1 year ago)
- Last Synced: 2025-10-10T19:09:25.798Z (8 months ago)
- Topics: duration, elapsed, temporal, time, web-component
- Language: HTML
- Homepage: https://time-duration.rbrd.in
- Size: 11.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @rbardini/time-duration
[](https://www.npmjs.com/package/@rbardini/time-duration)
[](https://github.com/rbardini/time-duration/actions)
⏱️ A web component to format `
> [!IMPORTANT]
> This component depends on APIs with limited availability across major browsers as of Oct 2024. See [polyfilling](#polyfilling) for more information.
```html
```
[View demos →](https://time-duration.rbrd.in)
## Installation
### Via package manager
```console
npm install @rbardini/time-duration
```
```js
import '@rbardini/time-duration/register'
```
### Via `` tag
[Download the latest release](https://github.com/rbardini/time-duration/releases) into your project and:
```html
<!-- host yourself -->
<script type="module" src="register.js">
```
or embed from a third-party CDN (update version as needed; not recommended for production use):
```html
```
```html
```
## Usage
`` must wrap a `
```html
```
> [!NOTE]
> Durations are formatted once and not updated in real time.
The `datetime` attribute will also be set to a [duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) representing the elapsed time, if not one already.
### Options
| Attribute | Description | Example | Default |
| ------------------- | ----------------------------------------------------- | -------------- | --------------------- |
| `data-ref-datetime` | The reference date and time of the resulting duration | `"2030-01-01"` | Current date and time |
> [!NOTE]
> Durations are never assumed to be negative—if the reference date and time is earlier than the target date and time, the duration is calculated from the reference to the target, otherwise from the target to the reference.
Data attributes are also forwarded as options to datetime/duration method calls. For example, to set the duration's `largestUnit` and `smallestUnit`, as well as the formatting `style`, simply declare them as data attributes:
```html
```
See [`datetime.until()`](https://tc39.es/proposal-temporal/docs/plaindatetime.html#until) and [`duration.toLocaleString()`](https://tc39.es/proposal-temporal/docs/duration.html#toLocaleString) for more options.
## Polyfilling
`` relies on the [`Temporal`](https://tc39.es/proposal-temporal/docs/) and [`Intl.DurationFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat) APIs to work, which are not widely available yet. You may want to wait until browser support improves before using this component.
If you want to use it today, however, you must _polyfill_ these APIs. You can include the [`temporal-polyfill`](https://github.com/fullcalendar/temporal-polyfill) and [`@formatjs/intl-durationformat`](https://formatjs.io/docs/polyfills/intl-durationformat/) polyfills in your project, for example.
Optionally, `` can load these polyfills from esm.sh for you via the `polyfill+register` entry point (not recommended for production use):
```js
import '@rbardini/time-duration/polyfill+register'
```
or
```html
```