Installation

Usage

Add the class dynamic-countdown to any element and configure it using data attributes. It is recommended to add placeholder text such as Loading... inside the element so users see something before the script runs.

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00">Loading...</span>

Configuration

Parameters

Tokens

The following tokens can be used in data-format. To use a letter literally without it being treated as a token, escape it with ! (e.g. !D outputs a literal D).

Wrapping a segment in square brackets (e.g. [D !days, ]) marks it as trimmable — when data-trim="true" is set, the entire segment is hidden if its value is 0. This does not apply to seconds tokens.

If a higher unit is not present in the format string, the next lower unit will display the total accumulated value. For example, if D is omitted, H will show total hours remaining rather than just the hours component.

Examples

Basic

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00">Loading...</span>

With timezone

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00" data-timezone="America/New_York">Loading...</span>

With trim

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00" data-format="[Y !years, ][M !months, ][D !days, ][H !hours, ][N !minutes and ][S !seconds]" data-trim="true">Loading...</span>

New Year countdown with rollover

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00" data-timezone="Europe/London" data-format="[D !days, ][H !hours, ][N !minutes and ][S !seconds]" data-end="Happy New Year!, 1h, 1y" data-trim="true">Loading...</span>

With event

<span class="dynamic-countdown" data-date="2027-01-01 00:00:00" data-event="true, newyear">Loading...</span>

document.addEventListener('countdownEnd', function(e) {
    if (e.detail.id === 'newyear') {
        // your code here
    }
});

Weekly Countdown

Every week, counts down to the same time next week forever.

<span class="dynamic-countdown"
    data-date="2026-04-26 18:44:00"
    data-format="[D !days, ][H !hours, ][N !minutes and ][S !seconds]"
    data-end="Anniversary of this script!!!!!, 30m, 7d"
    data-trim="true">
Loading...
</span>

New Year countdowns by timezone

The following table shows live New Year countdowns for a selection of timezones around the world.

Changelog

See Also

• DynamicClocks