@rbardini/time-duration

⏱️ A web component to format <time> elements with the elapsed time.

[!IMPORTANT] This component depends on APIs with limited availability across major browsers as of Oct 2024. See polyfilling for more information.

<time-duration>
  <time datetime="2020-01-01">
    <!-- 👇 will be replaced with current duration, e.g. "4 yrs, 6 mths" -->
    Jan 1, 2020 – Present
  </time>
</time-duration>

View demos →

Installation

Via package manager

npm install @rbardini/time-duration

import '@rbardini/time-duration/register'

Via <script> tag

Download the latest release into your project and:

<!-- host yourself -->
<script type="module" src="register.js"></script>

or embed from a third-party CDN (update version as needed; not recommended for production use):

<!-- esm.sh CDN -->
<script type="module" src="https://esm.sh/@rbardini/[email protected]/register"></script>

<!-- UNPKG CDN -->
<script type="module" src="https://www.unpkg.com/@rbardini/[email protected]/register.js"></script>

Usage

<time-duration> must wrap a <time> element with either a datetime attribute or a valid datetime text content:

<time-duration>
  <time datetime="2020-01-01">Jan 1, 2020 – Present</time>
</time-duration>

<!-- text content is used if no `datetime` attribute is defined -->
<time-duration>
  <time>2020-01-01</time>
</time-duration>

[!NOTE] Durations are formatted once and not updated in real time.

The datetime attribute will also be set to a duration string 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:

<time-duration data-largest-unit="year" data-smallest-unit="month" data-style="long">
  <time datetime="2020-01-01">Years since Jan 1, 2020</time>
</time-duration>

See datetime.until() and duration.toLocaleString() for more options.

Polyfilling

<time-duration> relies on the Temporal and 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 and @formatjs/intl-durationformat polyfills in your project, for example.

Optionally, <time-duration> can load these polyfills from esm.sh for you via the polyfill+register entry point (not recommended for production use):

import '@rbardini/time-duration/polyfill+register'

or

<script type="module" src="polyfill+register.js"></script>