Unobtrusive and easily skinable countdown jQuery plugin generating a <time> tag.
JavaScript HTML CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo Use jQuery 3.1.1 Dec 23, 2016
test
README.md Add new options to hide leading zeros for hours, minutes and seconds … Dec 23, 2016
jquery.countdown.js Bump to 1.2.8 Dec 23, 2016
package.json Bump to 1.2.8 Dec 23, 2016

README.md

jQuery Countdown

Unobtrusive and easily skinable countdown jQuery plugin generating a <time> tag.

Live demo.

Supported browsers

To use the countdown jQuery plugin you need an up-to-date web browser supporting the HTML5 time element.

Installation

Get the plugin from npm:

$ npm install jquery.countdown

Or include this script after jQuery.

<script src="jquery.js"></script>
<script src="jquery.countdown.js"></script>

Usage

Create a countdown from the value of the datetime attribute of a <time> tag (valid global date and time, time or duration).

<time datetime="2013-12-13T17:43:00">Friday, December 13th, 2013 5:43pm</time>
<time datetime="02:30:30">Expires in 2 hours 30 minutes 30 seconds</time>
<time datetime="P61D">61 days</time>

Create a countdown from a valid global date and time string (with time-zone offset).

<div>2012-12-08T17:47:00+0100</div><!-- Paris (winter) -->
<div>2012-12-08T08:47:00-0800</div><!-- California -->
<div>2012-12-08T16:47:00+0000</div><!-- UTC -->

Create a countdown from a valid time string.

<div>12:30</div>
<div>12:30:39</div>
<div>12:30:39.929</div>

Create a countdown from a valid duration string.

<div>P2D</div>
<div>PT01H01M15S</div>
<div>PT20M20S</div>
<div>PT10S</div>

Create a countdown from the string representation of a Python timedelta object.

<div>600 days, 3:59:12</div>
<div>00:59:00</div>
<div>3:59:12</div>

Create a countdown from a human readable duration string.

<h1>24h00m59s</h1>
<h1>2h 0m</h1>
<h1>4h 18m 3s</h1>
<h1>600 days, 3:59:12</h1>
<h1>600 jours, 3:59:12</h1>
<h1>00:01</h1>
<h1>240:00:59</h1>

Create a countdown from a string that can be interpreted by the JavaScript Date.parse() function.

<div><script>document.write(date.toDateString())</script></div>
<div><script>document.write(date.toGMTString())</script></div>
<div><script>document.write(date.toISOString())</script></div>
<div><script>document.write(date.toUTCString())</script></div>

Rock'n'roll

$('div, h1, time').countDown();

Available options

  • css_class: the css class of the generated <time> tag (default: countdown).
  • always_show_days: always display days if true even if none remains (default: false).
  • with_labels: display or hide labels (default: true).
  • with_seconds: display or hide seconds (default: true).
  • with_separators: display or hide separators between days, hours, minutes and seconds (default: true).
  • with_hh_leading_zero: always display hours in 2 digit format with a leading zero when appropriate (default: true).
  • with_mm_leading_zero: always display minutes in 2 digit format with a leading zero when appropriate (default: true).
  • with_ss_leading_zero: always display seconds in 2 digit format with a leading zero when appropriate (default: true).
  • label_dd: label's text for days (default: days).
  • label_hh: label's text for hours (default: hours).
  • label_mm: label's text for minutes (default: minutes).
  • label_ss: label's text for seconds (default: seconds).
  • separator: separator character between hours, minutes and seconds (default: :).
  • separator_days: separator character between days and hours (default: ,).

Events

time.elapsed: this event fires immediately when the time is elapsed.

$('#my-countdown').on('time.elapsed', function () {
    // do something...
});

time.tick: by default, this event fires every second(ish), the second passed parameter is the number of miliseconds left. Useful if you're doing something like a bar that fills up as time runs out.

$('#my-countdown').on('time.tick', function (ev, ms) {
    // do something...
});

Generated markup

A valid <time> tag representing a duration is generated.

<time class="countdown" datetime="P12DT05H16M22S">
    <span class="item item-dd">
        <span class="dd"></span>
        <span class="label label-dd">days</span>
    </span>
    <span class="separator separator-dd">,</span>
    <span class="item item-hh">
        <span class="hh-1"></span>
        <span class="hh-2"></span>
        <span class="label label-hh">hours</span>
    </span>
    <span class="separator">:</span>
    <span class="item item-mm">
        <span class="mm-1"></span>
        <span class="mm-2"></span>
        <span class="label label-mm">minutes</span>
    </span>
    <span class="separator">:</span>
    <span class="item item-ss">
        <span class="ss-1"></span>
        <span class="ss-2"></span>
        <span class="label label-ss">seconds</span>
    </span>
</time>

Acknowledgements

Released under the MIT License.

Issues should be opened through GitHub Issues.

jQuery Countdown is authored and maintained by Kemar.