A jQuery plugin that sets a `div` or `span` to show a countdown to a given time.

The current version is 2.0.2 and is available under the MIT licence. For more detail see the documentation reference page. Or see a minimal page that you could use as a basis for your own investigations.

- Defaults
- Formats 1
- Formats 2
- Layouts
- Significant
- Count Up
- Relative
- Pause/Lap
- Time Zones
- Callbacks
- Localisation
- Miscellaneous
- In the Wild
- Quick Ref

Default Settings

The countdown functionality can easily be added to a division with appropriate default settings, although you do need to set the target time. You can also remove the countdown widget if it is no longer required.

Default countdown:

    var newYear = new Date();
    newYear = new Date(newYear.getFullYear() + 1, 1 - 1, 1);
    $('#defaultCountdown').countdown({until: newYear});

    $('#removeCountdown').click(function() {
    	var destroy = $(this).text() === 'Remove';
    	$(this).text(destroy ? 'Re-attach' : 'Remove');
    	$('#defaultCountdown').countdown(destroy ? 'destroy' : {until: newYear});
    });

The defaults are:

- Text is in English
- Format is 'dHMS'
- Days are shown if needed
- Hours/minutes/seconds are shown

You can override the defaults globally as shown below:

    $.countdown.setDefaults({description: 'Until liftoff'});

Processed fields are marked with a class of `hasCountdown` and are not re-processed if targetted a second time.

A note on Date - the JavaScript `Date` constructor expects the year, month, and day as parameters. However, the month ranges from 0 to 11. To make explicit what date is intended (does a month of 3 mean March or April?) I specify the month from 1 to 12 and manually subtract the 1. Thus the following denotes 25 December, 2014.

    $(selector).countdown({since: new Date(2014, 12-1, 25)});

Basic Formats

You can control how the countdown is presented via the format setting. This is one or more of the following characters: 'Y' for years, 'O' for months, 'W' for weeks, 'D' for days, 'H' for hours, 'M' for minutes, 'S' for seconds. Use upper-case characters for required fields and the corresponding lower-case characters for display only if non-zero.

Don't show days:

    $('#noDays').countdown({until: liftoffTime, format: 'HMS'});

Don't show seconds:

    $('#noSeconds').countdown({until: liftoffTime, format: 'dHM'});

Don't show either:

    $('#noDaysSeconds').countdown({until: liftoffTime, format: 'HM'});

Pad with zeroes:

    $('#padZeroes').countdown({until: liftoffTime, padZeroes: true});

Compact version:

    $('#compact').countdown({until: liftoffTime, compact: true,
    	description: ''});

Minimal compact version:

    $('#minimal').countdown({until: liftoffTime, compact: true,
    	format: 'HM', description: ''});

Formatted description:

    $('#formatted').countdown({until: liftoffTime,
    	description: 'To the <i>next release</i> of <a href="' +
    	'http://jquery.com/plugins/project/countdown2">jQuery Countdown</a>!'});

Extended Formats

For targets further in the future, there are more presentation options.

Show it all:

    $('#showAll').countdown({until: longWayOff, format: 'YOWDHMS'});

By month:

    $('#byMonth').countdown({until: longWayOff, format: 'odHM'});

By week:

    $('#byWeek').countdown({until: longWayOff, format: 'wdHM'});

Strange combination:

    $('#strangeCombo').countdown({until: longWayOff, format: 'WHS'});

Compact version:

    $('#compactAll').countdown({until: longWayOff, compact: true,
    	format: 'YOWDHMS', description: ''});

Show all values as needed:

    $('#asNeeded').countdown({until: liftoffTime, format: 'yowdHMS'});

Show all values always:

    $('#alwaysShow').countdown({until: liftoffTime, format: 'YOWDHMS'});

Customised Layouts

Create your own customised layout for more control over the countdown appearance.

Indicate substitution points with '{desc}' for the description, '{sep}' for the time separator, '{pv}' where p is 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds and v is 'n' for the period value, 'nn' for the period value with a minimum of two digits, 'nnn' for the period value with a minimum of three digits, or 'l' for the period label (long or short form depending on the compact setting), or '{pd}' where p is as above and d is '1' for the units digit, '10' for the tens digit, '100' for the hundreds digit, or '1000' for the thousands digit.

If you need to exclude entire sections when the period value is zero and you have specified the period as optional, surround these sections with '{p<}' and '{p>}', where p is the same as above.

Your layout can just be simple text, or can contain HTML markup as well. You can even embed your HTML within the countdown division/span and reference it from there.

Simple text:

    $('#textLayout').countdown({until: liftoffTime,
    	layout: '{sn} {sl}, {mn} {ml}, {hn} {hl}, and {dn} {dl}'});

Unordered list:

    $('#listLayout').countdown({until: liftoffTime, format: 'yODHMS',
    	layout: '<ul>{y<}<li>{yn} {yl}</li>{y>}{o<}<li>{on} {ol}</li>{o>}' +
    	'{d<}<li>{dn} {dl}</li>{d>}{h<}<li>{hn} {hl}</li>{h>}' +
    	'{m<}<li>{mn} {ml}</li>{m>}{s<}<li>{sn} {sl}</li>{s>}</ul>'});

Compact with two digits:

    $('#compactLayout').countdown({until: liftoffTime, compact: true,
    	layout: 'just <b>{dn} {dl} {hnn}{sep}{mnn}{sep}{snn}</b> {desc}',
    	description: 'to wait'});

Using images with an embedded layout:

    <span id="imageLayout">
    	<span class="image{d10}"></span>
    	<span class="image{d1}"></span>
    	<span class="imageDay"></span>
    	<span class="imageSpace"></span>
    	<span class="image{h10}"></span>
    	<span class="image{h1}"></span>
    	<span class="imageSep"></span>
    	<span class="image{m10}"></span>
    	<span class="image{m1}"></span>
    	<span class="imageSep"></span>
    	<span class="image{s10}"></span>
    	<span class="image{s1}"></span>
    </span>

    $('#imageLayout').countdown({until: liftoffTime, compact: true,
    	layout: $('#imageLayout').html()});

    #imageLayout span { display: block; float: left; width: 10px; height: 21px;
    	background: url(img/countdownLED.png) no-repeat 0px 0px; }
    #imageLayout span.image0 { background-position: -0px 0px; }
    #imageLayout span.image1 { background-position: -10px 0px; }
    #imageLayout span.image2 { background-position: -20px 0px; }
    #imageLayout span.image3 { background-position: -30px 0px; }
    #imageLayout span.image4 { background-position: -40px 0px; }
    #imageLayout span.image5 { background-position: -50px 0px; }
    #imageLayout span.image6 { background-position: -60px 0px; }
    #imageLayout span.image7 { background-position: -70px 0px; }
    #imageLayout span.image8 { background-position: -80px 0px; }
    #imageLayout span.image9 { background-position: -90px 0px; }
    #imageLayout span.imageDay { background-position: -100px 0px; }
    #imageLayout span.imageSep { background-position: -110px 0px; }
    #imageLayout span.imageSpace { background-position: -120px 0px; }

Alternate images:

    $('#glowingLayout').countdown({until: liftoffTime, compact: true,
    	layout: '<span class="image{d10}"></span><span class="image{d1}"></span>' +
    		'<span class="imageDay"></span><span class="imageSpace"></span>' +
    		'<span class="image{h10}"></span><span class="image{h1}"></span>' +
    		'<span class="imageSep"></span>' +
    		'<span class="image{m10}"></span><span class="image{m1}"></span>' +
    		'<span class="imageSep"></span>' +
    		'<span class="image{s10}"></span><span class="image{s1}"></span>'});

    #glowingLayout span { display: block; float: left; width: 34px; height: 50px;
    	background: url(img/countdownGlowing.gif) no-repeat 0px 0px; }
    #glowingLayout span.image0 { background-position: -0px 0px; }
    #glowingLayout span.image1 { background-position: -34px 0px; }
    #glowingLayout span.image2 { background-position: -68px 0px; }
    #glowingLayout span.image3 { background-position: -102px 0px; }
    #glowingLayout span.image4 { background-position: -136px 0px; }
    #glowingLayout span.image5 { background-position: -170px 0px; }
    #glowingLayout span.image6 { background-position: -204px 0px; }
    #glowingLayout span.image7 { background-position: -238px 0px; }
    #glowingLayout span.image8 { background-position: -272px 0px; }
    #glowingLayout span.image9 { background-position: -306px 0px; }
    #glowingLayout span.imageDay { background-position: -340px 0px; }
    #glowingLayout span.imageSep { background-position: -374px 0px; }
    #glowingLayout span.imageSpace { background-position: -408px 0px; }

Significant Periods

Use the significant option to control how many significant (non-zero) periods are shown.

Show one significant period: compared to

    $('#significantLong1').countdown({until: longWayOff, format: 'YOWDHMS', significant: 1});
    $('#allLong1').countdown({until: longWayOff, format: 'YOWDHMS'});

Show two significant periods: compared to

    $('#significantLong2').countdown({until: longWayOff, format: 'YOWDHMS', significant: 2});
    $('#allLong2').countdown({until: longWayOff, format: 'YOWDHMS'});

Show one significant period: compared to

    $('#significantShort1').countdown({until: '+1h +1m +15s', format: 'YOWDHMS', significant: 1});
    $('#allShort1').countdown({until: '+1h +1m +15s', format: 'YOWDHMS'});

Show two significant periods: compared to

    $('#significantShort2').countdown({until: '+1h +1m +15s', format: 'YOWDHMS', significant: 2});
    $('#allShort2').countdown({until: '+1h +1m +15s', format: 'YOWDHMS'});

With a custom layout: compared to

    $('#significantLayout2').countdown({until: '+1h +1m +15s', significant: 2,
    	layout: '{d<}{dn} {dl} {d>}{h<}{hn} {hl} {h>}{m<}{mn} {ml} {m>}{s<}{sn} {sl}{s>}'});
    $('#allLayout2').countdown({until: '+1h +1m +15s',
    	layout: '{d<}{dn} {dl} {d>}{h<}{hn} {hl} {h>}{m<}{mn} {ml} {m>}{s<}{sn} {sl}{s>}'});

Count Up Since a Time

You can count up from a previous date/time, instead of down to a future date/time. Note that there will be no expiry event in this case.

Count up:

    $('#sinceCountdown').countdown({since: startYear,
    	format: 'YOWDHMS', description: 'Since New Year'});

Compact:

    $('#sinceCompact').countdown({since: startYear, compact: true,
    	format: 'YOWDHMS', description: ''});

Relative Times

You can set the until and since values relative to the current time, instead of as an absolute value. A number on its own is treated as seconds. Otherwise use a string to specify the number and units: 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, 's' for seconds. Either upper or lower case letters may be used. Multiple offsets may be combined into one setting.

Until 300 seconds time:

    $('#until300s').countdown({until: +300});

Until two days time:

    $('#until2d').countdown({until: '+2d'});

Since three weeks ago:

    $('#since3w').countdown({since: '-3W', description: 'Since last time'});

Until two days and four hours time:

    $('#until2d4h').countdown({until: '+2d +4h'});

Pause/Resume and Lap Times

You can pause and later resume a countdown from where you left off.

Pause/resume:

    $('#pauseResume').countdown({until: liftoffTime, onTick: showPauseTime});

    $('#pauseButton').click(function() {
    	var pause = $(this).text() === 'Pause';
    	$(this).text(pause ? 'Resume' : 'Pause');
    	$('#pauseResume').countdown(pause ? 'pause' : 'resume');
    });

    $('#toggleButton').click(function() {
    	$('#pauseResume').countdown('toggle');
    });

    function showPauseTime(periods) {
    	$('#showPauseTime').text(periods[4] + ':' + twoDigits(periods[5]) +
    		':' + twoDigits(periods[6]));
    }

Or you can pause to display a lap time while the countdown continues.

Lap time:

    $('#lapTime').countdown({until: liftoffTime, onTick: showLapTime});

    $('#lapButton').click(function() {
    	var pause = $(this).text() === 'Pause';
    	$(this).text(pause ? 'Resume' : 'Pause');
    	$('#lapTime').countdown(pause ? 'lap' : 'resume');
    });

    $('#toggleLapButton').click(function() {
    	$('#lapTime').countdown('toggleLap');
    });

    function showLapTime(periods) {
    	$('#showLapTime').text(periods[4] + ':' + twoDigits(periods[5]) +
    		':' + twoDigits(periods[6]));
    }

Time Zones and Synchronisation

Cater for time zones with the `timezone` setting, which is set to the target time's offset from GMT, in either hours or minutes. Alternately, use the `UTCDate` function to convert the target time to the equivalent UTC date/time.

If `timezone` is left at `null` it defaults to the timezone on the client.

Target time in Sydney, Australia (GMT +10:00):

    $('#sydneyCountdown').countdown({until: liftoffTime, timezone: +10});

Target time in Paris, France (GMT +01:00):

    $('#parisCountdown').countdown({until: liftoffTime, timezone: +60});

Target time in Los Angeles, USA (GMT -08:00):

    $('#laCountdown').countdown(
    	{until: $.countdown.UTCDate(-8, liftoffTime)});

You can also synchronise the client's time with that of the server. Provide a callback function for the `serverSync` setting that returns the current server time, usually from an AJAX call. The example below is only a simulation.

Server synchronisation (simulated 5 mins ahead):

    $('#syncCountdown').countdown(
    	{until: liftoffTime, serverSync: ahead5Mins});

    function ahead5Mins() {
    	var server = new Date();
    	server.setMinutes(server.getMinutes() + 5);
    	return server;
    }

In reality, you would have a program on the server responding with the current time and connect a function that retrieved it and presented it to the countdown. The following example uses a simple PHP program to return the date/time in a format directly usable by JavaScript. Remember to make the call synchronous and to include the timezone in the response.

    function serverTime() {
    	var time = null;
    	$.ajax({url: 'http://myserver.com/serverTime.php',
    		async: false, dataType: 'text',
    		success: function(text) {
    			time = new Date(text);
    		}, error: function(http, message, exc) {
    			time = new Date();
    	}});
    	return time;
    }

    <?php
    header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
    header("Expires: Fri, 1 Jan 2010 00:00:00 GMT"); // Date in the past
    header("Content-Type: text/plain; charset=utf-8"); // MIME type
    $now = new DateTime();
    echo $now->format("M j, Y H:i:s O")."\n";
    ?>

Or the equivalent Java servlet fragment:

    protected void doGet(HttpServletRequest request, HttpServletResponse response)
    		throws ServletException, IOException {
    	response.setHeader("Cache-Control", "no-cache, must-revalidate"); // HTTP/1.1
    	response.setHeader("Expires", "Fri, 1 Jan 2010 00:00:00 GMT"); // Date in the past
    	response.setHeader("Content-type", "text/plain; charset=utf-8"); // MIME type
    	String datetime = new SimpleDateFormat("MMM d, yyyy HH:mm:ss Z").format(new Date());
    	response.setHeader("Content-length", String.valueOf(datetime.length()));
    	response.getOutputStream().write(datetime.getBytes());
    }

Callback Events

On expiry a callback is made to allow you to action the countdown. You can force this event to fire even if the countdown starts after the target time by setting alwaysExpire to `true`.

You can also monitor the countdown on each tick of the clock.

Action it in 5 seconds:

    $('#shortly').countdown({until: shortly,
    	onExpiry: liftOff, onTick: watchCountdown});

    $('#shortlyStart').click(function() {
    	shortly = new Date();
    	shortly.setSeconds(shortly.getSeconds() + 5.5);
    	$('#shortly').countdown('option', {until: shortly});
    });

    function liftOff() {
    	alert('We have lift off!');
    }

    function watchCountdown(periods) {
    	$('#monitor').text('Just ' + periods[5] + ' minutes and ' +
    		periods[6] + ' seconds to go');
    }

Or do it your own way on the tick callback and hide the countdown `div` or `span`.

Every five seconds:

    $('#hidden').countdown({until: liftoffTime, format: 'HMS',
    	onTick: everyFive, tickInterval: 5});

    function everyFive(periods) {
    	$('#everyFive').text(periods[4] + ':' + twoDigits(periods[5]) +
    		':' + twoDigits(periods[6]));
    }

You can have a text message shown automatically on expiry.

Show message:

    $('#expireMessage').countdown({until: shortly,
    	expiryText: '<div class="over">It\'s all over</div>'});

    $('#expireMessageStart').click(function() {
    	shortly = new Date();
    	shortly.setSeconds(shortly.getSeconds() + 5.5);
    	$('#expireMessage').countdown('option', {until: shortly});
    });

Alternately, you can have a new page loaded automatically on expiry. Use the Back button to return.

Load new page:

    $('#newPage').countdown({until: shortly, expiryUrl: 'http://jquery.com',
    	description: 'To go to jQuery'});

    $('#newPageStart').click(function() {
    	shortly = new Date();
    	shortly.setSeconds(shortly.getSeconds() + 5.5);
    	$('#newPage').countdown('option', {until: shortly});
    });

Localisation

You can localise the countdown for other languages and regional differences (over 50 now available).

:

    $('#l10nCountdown').countdown({until: longWayOff,
    	format: 'YOWDHMS', description: 'Jusqu\'au décollage'});
    $('#l10nCompact').countdown({until: longWayOff, compact: true,
    	format: 'YOWDHMS', description: ''});

You need to load the appropriate language package, which adds a language set (`$.countdown.regionalOptions[langCode]`) and automatically sets this language as the default for all countdown divisions.

    <script type="text/javascript" src="jquery.countdown-fr.js"></script>

Thereafter, if desired, you can restore the original language settings.

    $.countdown.setDefaults($.countdown.regionalOptions['']);

And then configure the language per countdown.

    $('#l10n').countdown($.countdown.regionalOptions['fr']);
    $('#l10n').countdown($.extend({other options...}, $.countdown.regionalOptions['fr']));

Miscellaneous

Retrieve the current periods from a countdown timer.

Current periods:

    $('#timesCountdown').countdown({until: longWayOff, format: 'YOWDHMS'});

    $('#getNow').click(function() {
    	var periods = $('#timesCountdown').countdown('getTimes');
    	var text = '';
    	for (var i = 0; i < periods.length; i++) {
    		text += periods[i] + ' ' + $.countdown.regionalOptions[''].labels[i] + ' ';
    	}
    	$('#curPeriods').text(text);
    });

Highlight last five seconds:

    $('#highlightCountdown').countdown({until: 0,
    	onTick: highlightLast5});

    function highlightLast5(periods) {
    	if ($.countdown.periodsToSeconds(periods) === 5) {
    		$(this).addClass('highlight');
    	}
    }

    $('#highlightButton').click(function() {
    	$('#highlightCountdown').removeClass('highlight').
    		countdown('option', {until: +10});
    });

In the Wild

This tab highlights examples of this plugin in use "in the wild".

### Drupal Module

Provides the jQuery Countdown plugin, along with a simple API function (jquery_countdown_add) to easily add countdown/countup timer elements to the page. There is a submodule called "jQuery Countdown Block" - that can be used to provide one or more countdowns as a Block. It's very easy go to "admin/build/block" and click on the local task "Add countdown block". Now configure the countdown how ever you want. After save you have now a block that can be placed on every region.

### Story Timed

This site is all about writing stories together. You can contribute as much or little as you wish but the idea is to continue the theme and feeling of the story and most importantly have some fun and help others to enjoy the experience too! The countdown is used to time new contributions to the stories.

### OnlineStudentPlanner.com

OnlineStudentPlanner.com helps students achieve their academic goals by giving students tools to help them plan for their courses. With OnlineStudentPlanner.com you will be able to keep track of your school work, grades and appointments anywhere you are. By using the jQuery Countdown plugin you will always know how many days are left in your semester.

### Pick the Bucket

PickTheBucket enables donors to give directly to projects supporting vulnerable and disadvantaged children around the world. PickTheBucket is operated by Global Care, a UK-based, Christian international children's charity. PickTheBucket projects are operated by our international partners, running childcare centres, schools, feeding and training programmes worldwide. The countdowns apply to the various buckets available.

### Startup Death Clock

The startup death clock tells you what day your startup will run out of money. The countdown plugin is used to display a big scary LCD clock.

### Meeting Manager

This extremely simple application allows you to maximize the effectiveness of your team's time during meetings. By providing the total number of participants and either their average hourly salary or average yearly salary, we calculate exactly how much money per second that meeting is costing your company/team.

### 2BTHR

2BTHR is a simple and fun web application allowing you to create an event by entering a location and then using Google Maps to plot your destination. You can then share the event with your friends and family via Twitter and Facebook!

### Pennantchase.com

Pennant Chase is a free baseball simulation website with over 600 active leagues. Baseball fans can draft their teams based on real historical statistics. The countdown is used in the private draft rooms to enforce picks in a timely manner. League commissioners can set a desired timer length, and the countdown re-sets after each pick is made.

### SharePoint WebPart

A SharePoint WebPart to display the real-time remaining time until a specific date or event using jQuery/JavaScript.

### Ominder - Organize Your Life Events

Ominder is simple and clean event reminder website where users can keep track of their birthdays, anniversaries and much more. Ominder will notify users when an event is about to occur so you never forget. The countdown timer is used to show the user how much time is remaining until their event will occur.

To add another example, please contact me (kbwood{at}iinet.com.au) and provide the plugin name, the URL of your site, its title, and a short description of its purpose and where/how the plugin is used.

Quick Reference

A full list of all possible settings is shown below. Note that not all would apply in all cases. For more detail see the documentation reference page.

    $(selector).countdown({
    	labels: ['Years', 'Months', 'Weeks', 'Days', 'Hours', 'Minutes', 'Seconds'],
    		// The expanded texts for the counters
    	labels1: ['Year', 'Month', 'Week', 'Day', 'Hour', 'Minute', 'Second'],
    		// The display texts for the counters if only one
    	compactLabels: ['y', 'm', 'w', 'd'], // The compact texts for the counters
    	whichLabels: null, // Function to determine which labels to use
    	digits: ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'], // The digits to display
    	timeSeparator: ':', // Separator for time periods
    	isRTL: false, // True for right-to-left languages, false for left-to-right

    	until: null, // new Date(year, mth - 1, day, hr, min, sec) - date/time to count down to
    		// or numeric for seconds offset, or string for unit offset(s):
    		// 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds
    	since: null, // new Date(year, mth - 1, day, hr, min, sec) - date/time to count up from
    		// or numeric for seconds offset, or string for unit offset(s):
    		// 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds
    	timezone: null, // The timezone (hours or minutes from GMT) for the target times,
    		// or null for client local
    	serverSync: null, // A function to retrieve the current server time for synchronisation
    	format: 'dHMS', // Format for display - upper case for always, lower case only if non-zero,
    		// 'Y' years, 'O' months, 'W' weeks, 'D' days, 'H' hours, 'M' minutes, 'S' seconds
    	layout: '', // Build your own layout for the countdown
    	compact: false, // True to display in a compact format, false for an expanded one
    	padZeroes: false, // True to add leading zeroes
    	significant: 0, // The number of periods with values to show, zero for all
    	description: '', // The description displayed for the countdown
    	expiryUrl: null, // A URL to load upon expiry, replacing the current page
    	alwaysExpire: false, // True to trigger onExpiry even if never counted down
    	onExpiry: null, // Callback when the countdown expires -
    		// receives no parameters and 'this' is the containing division
    	onTick: null, // Callback when the countdown is updated -
    		// receives int[7] being the breakdown by period (based on format)
    		// and 'this' is the containing division
    	tickInterval: 1 // Interval (seconds) between onTick callbacks
    });

    $.countdown.regionalOptions[] // Language/country-specific localisations

    $.countdown.setDefaults(settings) // Set global defaults

    $.countdown.UTCDate(tz, time) // Standardise a date to UTC format
    $.countdown.UTCDate(tz, year, month, day, hours, mins, secs, ms)

    $.countdown.periodsToSeconds(periods) // Convert periods into equivalent seconds

    $.countdown.resync() // Re-synchronise all countdown instances with their server

    $(selector).countdown('option', options) // Change instance settings
    $(selector).countdown('option', name, value) // Change a single instance setting

    $(selector).countdown('option', name) // Retrieve instance settings

    $(selector).countdown('destroy') // Remove countdown functionality

    $(selector).countdown('pause') // Stop the countdown but don't clear it
    $(selector).countdown('lap') // Stop the display but continue the countdown
    $(selector).countdown('resume') // Restart a paused or lap countdown
    $(selector).countdown('toggle') // Toggle between pause/resume
    $(selector).countdown('toggleLap') // Toggle between lap/resume

    $(selector).countdown('getTimes') // Retrieve the current time periods

Usage

1. Include the jQuery library (1.4+) in the head section of your page.

       <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>

2. Download and include the jQuery Countdown CSS and JavaScript in the head section of your page.

       <link rel="stylesheet" type="text/css" href="css/jquery.countdown.css">
       <script type="text/javascript" src="js/jquery.plugin.js"></script>
       <script type="text/javascript" src="js/jquery.countdown.js"></script>

   Alternately, you can use the minimised version `jquery.countdown.min.js` (13.6K vs 35.0K, 4.5K when zipped).
3. Connect the countdown functionality to your divs.

       $(selector).countdown({until: liftoffTime});

   You can include custom settings as part of this process.

       $(selector).countdown({until: liftoffTime, format: 'dHM'});

For more detail see the documentation reference page. Or see a minimal page that you could use as a basis for your own investigations.

Localisations

Localisation packages are available for download and should be loaded after the main time entry code. These packages automatically apply their settings as global default values.

- Albanian (Gjuha shqipe) - jquery.countdown-sq.js (thanks to Erzen Komoni)
- Arabic (العربية) - jquery.countdown-ar.js (thanks to Talal Al Asmari)
- Armenian (Հայերեն) - jquery.countdown-hy.js (thanks to Artur Martirosyan)
- Bengali/Bangla (বাংলা) - jquery.countdown-bn.js (thanks to Mohammed Tajuddin)
- Bosnian (Bosanski) - jquery.countdown-bs.js (thanks to Miralem Mehic)
- Bulgarian (български език) - jquery.countdown-bg.js (thanks to Manol Trendafilov)
- Burmese (မြန်မာစာ) - jquery.countdown-my.js (thanks to Win Lwin Moe)
- Catalan (Català) - jquery.countdown-ca.js (thanks to Miquel Casas)
- Chinese/Simplified (简体中文) - jquery.countdown-zh-CN.js (thanks to Cloudream)
- Chinese/Traditional (繁體中文) - jquery.countdown-zh-TW.js (thanks to Cloudream)
- Croatian (Hrvatski jezik) - jquery.countdown-hr.js (thanks to Dejan Broz and zytzagoo)
- Czech (Čeština) - jquery.countdown-cs.js (thanks to Roman Chlebec)
- Danish (Dansk) - jquery.countdown-da.js (thanks to Kasper Buch)
- Dutch (Nederlands) - jquery.countdown-nl.js (thanks to Mathias Bynens)
- Estonian (eesti keel) - jquery.countdown-et.js (thanks to Helmer Aaviksoo)
- Faroese (føroyskt) - jquery.countdown-fo.js (thanks to Kasper Friis Christensen)
- Farsi/Persian (فارسی) - jquery.countdown-fa.js (thanks to Alireza Ziaie)
- Finnish (suomi) - jquery.countdown-fi.js (thanks to Kalle Vänskä and Juha Suni)
- French (Français) - jquery.countdown-fr.js
- Galician (Galego) - jquery.countdown-gl.js (thanks to Moncho Pena and Angel Farrapeira)
- German (Deutsch) - jquery.countdown-de.js (thanks to Samuel Wulf)
- Greek (Ελληνικά) - jquery.countdown-el.js (thanks to Philip)
- Gujarati (ગુજરાતી) - jquery.countdown-gu.js (thanks to Sahil Jariwala)
- Hebrew (עברית) - jquery.countdown-he.js (thanks to Nir Livne)
- Hungarian (Magyar) - jquery.countdown-hu.js (thanks to Edmond L.)
- Indonesian (Bahasa Indonesia) - jquery.countdown-id.js (thanks to Erwin Yonathan)
- Icelandic (Íslenska) - jquery.countdown-is.js (thanks to Róbert Karl Lárusson)
- Italian (Italiano) - jquery.countdown-it.js (thanks to Davide Bellettini and Roberto Chiaveri)
- Japanese (日本語) - jquery.countdown-ja.js (thanks to Ken Ishimoto)
- Kannada (ಕನ್ನಡ) - jquery.countdown-kn.js (thanks to Guru Chaturvedi)
- Korean (한국어) - jquery.countdown-ko.js (thanks to Ryan Yu)
- Latvian (Latviešu Valoda) - jquery.countdown-lv.js (thanks to Jānis Peisenieks)
- Lithuanian (lietuvių kalba) - jquery.countdown-lt.js (thanks to Moacir)
- Malayalam (മലയാളം) jquery.countdown-ml.js (thanks to Harilal.B)
- Malaysian (Bahasa Melayu) - jquery.countdown-ms.js (thanks to Jason Ong)
- Norwegian (Bokmål) - jquery.countdown-nb.js (thanks to Kristian Ravnevand)
- Polish (Polski) - jquery.countdown-pl.js (thanks to Pawel Lewtak)
- Portuguese/Brazilian (Português) - jquery.countdown-pt-BR.js (thanks to Marcelo Pellicano de Oliveira and Juan Roldan)
- Romanian (Română) - jquery.countdown-ro.js (thanks to Edmond L.)
- Russian (Русский) - jquery.countdown-ru.js (thanks to Sergey K.)
- Serbian (српски језик) - jquery.countdown-sr.js (thanks toPredrag Leka)
- Serbian (srpski jezik) - jquery.countdown-sr-SR.js (thanks to Predrag Leka)
- Slovak (Slovenčina) - jquery.countdown-sk.js (thanks to Roman Chlebec)
- Slovenian (Slovenščina) - jquery.countdown-sl.js (thanks to Borut Tomažin and Jan Zavrl)
- Spanish (Español) - jquery.countdown-es.js (thanks to Sergio Carracedo Martinez)
- Swedish (Svenska) - jquery.countdown-sv.js (thanks to Carl)
- Thai (ภาษาไทย) - jquery.countdown-th.js (thanks to Pornchai Sakulsrimontri)
- Turkish (Türkçe) - jquery.countdown-tr.js (thanks to Bekir Ahmetoğlu)
- Ukrainian (українська мова) - jquery.countdown-uk.js (thanks to Misha Goloborodko and Iгор Kоновал)
- Urdu (‫اُردوُ‬) - jquery.countdown-ur.js (thanks to Azhar Rasheed)
- Uzbek (O‘zbek tili) - jquery.countdown-uz.js (thanks to Alisher Ulugbekov)
- Vietnamese (Tiếng Việt) - jquery.countdown-vi.js (thanks to Pham Tien Hung)
- Welsh (Cymraeg) - jquery.countdown-cy.js (thanks to Gareth Jones)

Other translations are welcomed.

Comments

> It's awesome! You saved me a lot of time trying to create something that does the equivalent...

Daniel McGhan

> Estou usando seu script, muito bom, jQuery Countdown.

Tulio Galli

> Thank you very much for your countdown timer. I used it on my new website and it's totally critical to the functionality of the site.

Alasdair Boyd

> I just want to start by saying I really like this plug-in. It's very easy to customize.

Mickey Elliott

> Wonderful plugin. Very easy to use and modify.

Danielle Swank

Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.

Change History

Version | Date | Changes
--- | --- | ---
2.0.2 | 10 Jan 2015 | Added `resync` function Corrected Spanish localisation
2.0.1 | 12 Jul 2014 | Corrected resetting of labels Added Faroese and Icelandic localisations Corrected Croatian localisation
2.0.0 | 25 Jan 2014 | Updated underlying plugin framework Changed `regional` to `regionalOptions` Added `toggle` and `toggleLap` commands Added `padZeroes` option Safeguarded `performance` access Removed `br` from standard layout and style with CSS instead Added Urdu localisation
1.6.3 | 03 Aug 2013 | Corrected layouts derived from markup Corrected timing callbacks for older IE
1.6.2 | 27 Apr 2013 | Don't recalculate target time if not supplied on option change Corrected clearing of labels when changing Corrected retrieval of time periods when paused Added Malayalam localisation Corrected Farsi and Korean localisations
1.6.1 | 15 Dec 2012 | Corrected internal target tracking Corrected for IE10/Chrome high resolution timer Added Albanian, Gujarati, and Uzbek localisations Corrected Galician and Italian localisations
1.6.0 | 04 Aug 2012 | Added `$.noRequestAnimationFrame` to force use of `setInterval` Added `digits` option to localisations to allow for alternate digit characters Changed `change` command to `option` Changed `settings` command to `option` Updated underlying plugin framework Added Armenian, Kannada and Welsh localisations Corrected Portuguese/Brazilian and Ukranian localisations Added Arabic digits to Arabic localisation
1.5.11 | 15 Oct 2011 | Corrected `requestAnimationFrame` usage for IE
1.5.10 | 08 Oct 2011 | Use `requestAnimationFrame` when available Added Estonian localisation
1.5.9 | 05 Mar 2011 | Added Bengali/Bangla, Croatian, Greek, Malaysian, Serbian/Cyrillic, Serbian/Latin, Slovenian and Vietnamese localisations Corrected Russian localisation
1.5.8 | 15 May 2010 | Added `significant` to restrict number of period amounts shown Added `whichLabels` for greater control over singular/plural forms of labels Corrected period calculation for count-ups involving years/months Added Bulgarian localisation
1.5.7 | 27 Mar 2010 | Added `tickInterval` to space out `onTick` callbacks Only call `serverSync` once per server Added Catalan and Thai localisations
1.5.6 | 13 Feb 2010 | Allowed countdown to count up from zero Corrected error when counting up into an optional time component Added `periodsToSeconds` function Added Burmese, Finnish, Galician, Latvian, and Lithuanian localisations
1.5.5 | 14 Nov 2009 | Countdown rounds up remainders, e.g. showing hours and minutes only, the countdown shows 1 minute for the last minute Added substitutions to `layout` setting: `p1000` for the thousands digit of periods Added 'settings' command to retrieve property value(s)
1.5.4 | 26 Sep 2009 | Added `serverSync` setting for external synchronisation Corrected styling for IE8 Added Japanese localisation
1.5.3 | 01 Aug 2009 | Added substitutions to `layout` setting: `pnnn` for periods with minimum three digits, `pd` for individual digits of periods, `desc` for countdown description, `sep` for time separator Added Korean localisation
1.5.2 | 09 May 2009 | Added `expiryText` setting for a simple message on expiry Prevented infinite loop when changing settings in `onExpiry` callback Fixed negative counts when target date is exactly n months away but earlier in the day Fixed end of month processing for year/month periods Fixed timezone adjustment near end of month
1.5.1 | 11 Apr 2009 | Replaced `serverTime` setting with `timezone` Added `UTCDate` function Fixed error when resetting a stopped countdown
1.5.0 | 28 Mar 2009 | Changed layout definitions 'change' command now accepts a single named property and value Changed internal `div`s to `span`s All countdowns on a page run off the one timer Added Danish and Ukrainian localisations
1.4.3 | 07 Feb 2009 | Pass function to `setTimeout` Added Indonesian and Norwegian localisations Updated Romanian localisation
1.4.2 | 13 Dec 2008 | Enhanced plural period terms for Slavic languages Replaced `labelsSingle` and `compactLabelsSingle` with `labels1` and `compactLabels1` if necessary Added `isRTL` setting for right-to-left languages Added Hebrew, Russian, Slovak, and Swedish localisations Updated Czech localisation
1.4.1 | 18 Oct 2008 | Bug fix for compact times with hours/minutes/seconds Added Persian localisation
1.4.0 | 04 Oct 2008 | Added `layout` setting for custom layouts Added Turkish localisation
1.3.0 | 05 July 2008 | Internal changes for instance values Added 'getTimes' command to retrieve array of current periods Added 'pause', 'lap', and 'resume' commands to allow pausing and resuming of countdowns
1.2.2 | 14 June 2008 | Bug fix for compact times with hours/minutes/seconds
1.2.1 | 07 June 2008 | Added relative values for `until` and `since` Added `serverTime` option to allow for time zone differences Added `alwaysExpire` option to force the `onExpiry` event if starting after the target time Added `labelsSingle` and `compactLabelsSingle` options for labels applying to a singular period Added Polish localisation
1.2.0 | 03 May 2008 | Added `since` option for counting up Added Czech, Dutch, Hungarian, Portuguese (Brazilian), Romanian, and Spanish localisations
1.1.1 | 23 Feb 2008 | Corrected bugs in period calculations for years/months Changed 'remove' command to 'destroy'
1.1.0 | 16 Feb 2008 | Updated interface to conform to jQuery UI standards Replaced `showDays` and `showSeconds` with `format` setting Added `expiryUrl` setting Added Simplified Chinese, Traditional Chinese, Italian localisations Added backwards compatibility module for v1.0
1.0.0 | 26 Jan 2008 | Initial release