This script is the improved version of the script Countdown, with a few differences of functions. Another version of this script is CountdownScroller which makes the scrolling effect in the countdown.

Installation

Instruction

Below is the countdown clock format that can be added to a page.

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z"></span>

The example above gives the result:

Any text added in both ends of the format above appears, but the text inside the tag disappears when countdown runs.

Time left: <span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z">Countdown test</span> until new year!

The example above gives the result:

Time left: Countdown test until new year!

Below is the guideline that users can customize how the countdown is displayed only using a single line, based on their preferences.

Note: Users can change the tag "span" to "div", but the style should be customized if the change happens.

Time format

Countdown currently uses ISO 8601 as a standard date and time format. Users can customize the time to make countdown for their preferences, such as upcoming events or movies.

data-countdown="2027-01-01T00:00:00Z"

Some other formats are also applied, such as:

data-countdown="January 1, 2026 00:00:00" -- For date format in United States

data-countdown="1 January 2026 00:00:00" -- For date format in other countries

data-countdown="January 1, 2026 00:00:00 +0700" -- For date format in different time fluctuation. +7 hours, for example

data-countdown="1 January 2026 00:00:00 EST" -- For date format with specific time zone identifier. GMT, for example

data-countdown="12/31/2025 23:59:59" -- For date format in abbreviation, written as MM/DD/YYYY, dot "." or hyphen "-" is valid

Note that the default time zone uses UTC. Users need to determine the time zone identifier in their geographic location and adjust the time appropriately. Otherwise, the countdown won't display correct time as expected.

Attribute

There are 6 attributes used inside HTML tag:

1. data-countdown
2. data-countdown-options
3. data-countdown-message
4. data-countdown-date-start
5. data-countdown-progress
6. data-countdown-start

• 1. data-countdown

Mentioned above, determine the date to start countdown. This attribute is required. Otherwise, countdown does not run.

If time format is not valid or not written in the attribute, countdown also does not run and an error message appears.

Note that countdown must be a future date. If time format added is a past date, countdown stops immediately.

• 2. data-countdown-options

Add option to determine how the countdown will look like. By default, the display format of the countdown is "DDD-HH:MM:SS".

data-countdown-options uses 4 values: "no-date-leading-zero", "no-time-leading-zero", "time-text-day" and "time-text-hms".

no-date-leading-zero: remove zeros if available before the digits for day. For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-options="no-date-leading-zero"></span>

gives:

no-time-leading-zero: remove zeros if available before the digits for hour, minute and second. For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-options="no-time-leading-zero"></span>

gives:

time-text-day: display text "day" that replaces the current symbol "-". For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-options="time-text-day"></span>

gives:

time-text-hms: display text "hour, minute, second" that replaces the current symbol ":". For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-options="time-text-hms"></span>

gives:

This attribute is optional, but users can use or combine the options based on their preferences. For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-options="time-text-day no-date-leading-zero"></span>

gives day text format and removes zeros before the digits for day:

• 3. data-countdown-message

Add a message after countdown ends and it will replace the countdown format. By default, countdown will stop with the format "00:00:00". This attribute is optional.

For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-message="Happy new year!"></span>

The message "Happy new year!" will display which replaces the countdown after it reaches 0.

• 4. data-countdown-date-start

Start countdown for a specific day.

For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-date-start="30"></span>

gives:

At this time, only day digits are displayed. The rest of the countdown still runs in the background. Until the day reaches "30", the full countdown format will show.

• 5. data-countdown-progress

Add a progress bar above the countdown. This attribute is optional, mostly for decoration. By default, the progress bar runs from right to left.

data-countdown-progress uses only 1 value: "true".

For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-progress="true"></span>

gives:

Note that when users reload page, the progress bar will be reset automatically. So this attribute below may help.

• 6. data-countdown-start

Add a specific date in the past. This attribute is optional. It supports data-countdown-progress in displaying the progress bar properly even reloading page.

For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z" data-countdown-start="2026-01-01T00:00:00Z" data-countdown-progress="true"></span>

gives:

This table below summarizes attributes which can be used in the HTML tag.

Configuration

For example, do not hide day, show 2 day digits, change separator in the countdown, and change direction of the progress bar:

window.CountdownRegular = {
	hideDay: false,
    dayPadding: 2,
    daySeparator: '/',
    hmsSeparator: '.',
    reverseProgress: true,
};

Fallback

Since the script does not run on mobile. Users need to consider adding a plain text inside the HTML content. For example:

<span class="countdown-regular" data-countdown="2027-01-01T00:00:00Z">2027-01-01T00:00:00Z</span>

When the visitors view any pages which are using this countdown in mobile view, only the plain text shows to avoid empty content being generated.

Changelog

See also

• Countdown
• CountdownScroller