$(countdown)
$(countdown <iso time or epoch ms> [showHours] [showMinutes] [allowNegative])
Counts down to a point in time. It works out how many seconds are left until that time and formats the result like $(formatDuration), with colon-separated, zero-padded components.
The time can be an ISO time (such as 2026-10-02T20:00:00Z) or a number of milliseconds since 1970 (epoch milliseconds).
On overlays the result updates every second by itself.
Flags
Add optional flags after the time to control the output:
| Flag | Effect |
|---|---|
showMinutes | Always display minutes and seconds (MM:SS), even when under a minute |
showHours | Always display hours, minutes and seconds (HH:MM:SS), even when under an hour |
allowNegative | Keep counting past the time (shown with a minus sign). Without it, the result stops at 0 |
tip
Use showHours for a clock that keeps the same width the whole way down.
Examples
| Expression | Output |
|---|---|
$(countdown 2026-10-02T20:00:00Z) | 45:10 (with 45 minutes 10 seconds to go) |
$(countdown 2026-10-02T20:00:00Z showHours) | 00:45:10 |
With a widget's live values
Widgets that publish an end time can feed it straight in. The Countdown Timer widget does this:
$(countdown {{subtreeContext.countdownTimer.endsAt}} showHours)
→ 01:23:45
The Ad Break widget works the same way with {{subtreeContext.adBreak.endsAt}}.