Duration
<quiet-duration>
Formats a length of time as a human-readable phrase. Reach for a duration to show elapsed time, timers, or estimated reading times.
Provide the length of time in seconds and the component balances it into larger units, rounds it to the
precision you ask for, and renders it in the user's language. It's the counterpart to
<quiet-relative-time>, which describes when something happened rather than how long it lasted.
<quiet-duration seconds="5400"></quiet-duration>
This component uses the
API, which is part of
Baseline
. In unsupportive browsers, the duration falls back to a compact format such as 1h 30m.
Examples Jump to heading
Changing the format Jump to heading
You can change how the duration is displayed with the format attribute. Available options
include long, short, narrow, and digital.
<quiet-duration format="long" seconds="5400"></quiet-duration><br>
<quiet-duration format="short" seconds="5400"></quiet-duration><br>
<quiet-duration format="narrow" seconds="5400"></quiet-duration><br>
<quiet-duration format="digital" seconds="5400"></quiet-duration>
Controlling precision Jump to heading
By default, durations are shown from days down to minutes. Use max-unit and
min-unit to change the range of units that appear. Both accept years,
months, weeks, days, hours, minutes, and
seconds.
The min-unit attribute sets the smallest unit shown and the duration is rounded to it. A cat's
ten-minute grooming session, measured to the second, reads more calmly when rounded to minutes.
<!-- 632 seconds, to the second -->
<quiet-duration seconds="632" min-unit="seconds"></quiet-duration><br>
<!-- the same nap, rounded to minutes -->
<quiet-duration seconds="632" min-unit="minutes"></quiet-duration>
The max-unit attribute sets the largest unit shown. Time that exceeds it rolls up into that
unit instead of spilling over into larger ones, which is handy when you'd rather count a long duration in
hours than in days.
<!-- rolls up into days -->
<quiet-duration seconds="180000" max-unit="days"></quiet-duration><br>
<!-- counted entirely in hours -->
<quiet-duration seconds="180000" max-unit="hours"></quiet-duration>
Months and years vary in length, so how they're calculated depends on how the duration is set. With
since or until, they're counted from the calendar and are exact. With
seconds, there are no dates to count between, so they're estimated using an average month and
a 365.25-day year, which can be off by a day or two over long spans.
Setting the duration with a property Jump to heading
For durations calculated at runtime, such as the time between two dates, set the
seconds property in JavaScript.
<quiet-duration id="duration__computed"></quiet-duration>
<script>
const duration = document.getElementById('duration__computed');
const start = new Date('2024-01-01T09:00:00');
const end = new Date('2024-01-01T17:45:00');
duration.seconds = (end - start) / 1000; // 8 hours, 45 minutes
</script>
Elapsed and remaining time Jump to heading
You can anchor the duration to a point in time and the component will measure the gap between then and now,
ignoring seconds. Use since for a past date to count elapsed time up, or
until for a future date to count remaining time down. Once an anchor passes, the duration
reaches zero.
Like the other date components, an attribute value should be an
ISO 8601
, while a property can be a Date object.
<!-- time elapsed since a past date -->
<quiet-duration id="duration__since" min-unit="minutes"></quiet-duration><br>
<!-- time remaining until a future date -->
<quiet-duration id="duration__until" min-unit="minutes"></quiet-duration>
<script>
const since = document.getElementById('duration__since');
const until = document.getElementById('duration__until');
since.since = new Date(Date.now() - 45 * 60 * 1000); // 45 minutes ago
until.until = new Date(Date.now() + 3 * 60 * 60 * 1000); // 3 hours from now
</script>
Updating live Jump to heading
Add the live attribute to update the duration automatically as time passes. This is most useful
with since or until, where it counts up like a stopwatch or down like a countdown.
Use min-unit="seconds" to watch it tick.
<quiet-duration live min-unit="seconds" id="duration__live"></quiet-duration>
<br><br>
<quiet-button>Reset</quiet-button>
<script>
const duration = document.getElementById('duration__live');
const button = duration.parentElement.querySelector('quiet-button');
duration.since = new Date();
button.addEventListener('click', () => {
duration.since = new Date();
});
</script>
For phrases like "3 minutes ago," reach for relative time instead. Duration shines when you want compound units ("1 hour, 30 minutes") or a ticking clock, which relative time can't produce.
Localizing durations Jump to heading
Set the lang attribute on the element to change the language.
<quiet-duration lang="es" seconds="5400"></quiet-duration><br>
<quiet-duration lang="de" seconds="5400"></quiet-duration><br>
<quiet-duration lang="ru" seconds="5400"></quiet-duration>
This component also updates based on the page's language, which can be set using
<html lang="…">.
API Jump to heading
Importing Jump to heading
The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.
To manually import <quiet-duration> from the CDN, use the following code.
import 'https://cdn.quietui.org/v5.3.1/components/duration/duration.js';
To manually import <quiet-duration> from a self-hosted distribution, use the
following code. Remember to replace /path/to/quiet with the appropriate local path.
import '/path/to/quiet/components/duration/duration.js';Properties Jump to heading
Duration has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties
| Property | Description | Reflects | Type | Default |
|---|---|---|---|---|
seconds
|
The length of time to format, in seconds. Negative values are treated as zero. Ignored when
since or until is set.
|
|
number
|
0
|
since
|
A past date to measure elapsed time from. If an attribute is passed, the date should be an
ISO 8601
. If set as a property, a Date object can be used instead. When provided, the time
elapsed from this date until now is shown instead of seconds, counting up. Combine with
live to update it automatically.
|
|
Date |
string
|
|
until
|
A future date to measure remaining time until. Accepts the same values as since. When
provided, the time remaining from now until this date is shown instead of seconds,
counting down. Reaches zero once the date passes. Combine with live to update it
automatically.
|
|
Date |
string
|
|
format
|
The style of duration to render. Use digital to show a clock-style format such as
1:30:00.
|
|
'long' |
'short' |
'narrow' |
'digital'
|
'long'
|
maxUnit
max-unit
|
The largest unit to display. Time that exceeds this unit rolls up into it. |
|
DurationUnit
|
'days'
|
minUnit
min-unit
|
The smallest unit to display. The duration is rounded to this unit. |
|
DurationUnit
|
'minutes'
|
live
|
When set, the duration will update itself. Most useful alongside since or
until to count as time passes.
|
|
boolean
|
false
|