jQuery Countdown

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:   Remove

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

$('#removeCountdown').toggle(function() {
		$(this).text('Re-attach');
		$('#defaultCountdown').countdown('destroy');
	},
	function() {
		$(this).text('Remove');
		$('#defaultCountdown').countdown({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, 2010.

$(selector).countdown({since: new Date(2010, 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'});

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:   Pause

 

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

$('#pauseButton').toggle(function() {
		$(this).text('Resume');
		$('#pauseResume').countdown('pause');
	},
	function() {
		$(this).text('Pause');
		$('#pauseResume').countdown('resume');
	}
);

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:   Pause

 

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

$('#lapButton').toggle(function() {
		$(this).text('Resume');
		$('#lapTime').countdown('lap');
	},
	function() {
		$(this).text('Pause');
		$('#lapTime').countdown('resume');
	}
);

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:   Start

 

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

$('#shortlyStart').click(function() {
	shortly = new Date();
	shortly.setSeconds(shortly.getSeconds() + 5.5);
	$('#shortly').countdown('change', {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:   Start

$('#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('change', {until: shortly});
});

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

Load new page:   Start

$('#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('change', {until: shortly});
});

Localisation

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

‫العربية (Arabic) Bahasa Indonesia (Indonesian) Bahasa Melayu (Malaysian) বাংলা (Bengali/Bangla) Bokmål (Norwegian) Bosanski (Bosnian) български език (Bulgarian) Català (Catalan) Čeština (Czech) Cymraeg (Welsh) Dansk (Danish) Deutsch (German) eesti keel (Estonian) Ελληνικά (Greek) Español (Spanish) ‫فارسی (Farsi/Persian) Français (French) Galego (Galician) 한국어 (Korean) ‫עברית (Hebrew) Hrvatski jezik (Croatian) Հայերեն (Armenian) Italiano (Italian) ಕನ್ನಡ (Kannada) Latviešu Valoda (Latvian) lietuvių kalba (Lithuanian) Magyar (Hungarian) မြန်မာစာ (Burmese) Nederlands (Dutch) 日本語 (Japanese) ภาษาไทย (Thai) Polski (Polish) Português (Portuguese/Brazilian) Română (Romanian) Русский (Russian) Slovenčina (Slovak) Slovenščina (Slovenian) српски језик (Serbian) srpski jezik (Serbian) suomi (Finnish) Svenska (Swedish) Tiếng Việt (Vietnamese) Türkçe (Turkish) українська мова (Ukranian) 简体中文 (Chinese/Simplified) 繁體中文 (Chinese/Traditional) :

 

$('#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.regional[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.regional['']);

And then configure the language per countdown.

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

Miscellaneous

Add curvy corners to your countdown. You need to wrap the countdown division in another division to which the curvy corners are applied.

Curvy-corners:

try {
	$('#curvyWrapper').corner();
}
catch (e) {
	// Ignore - problem in IE8
}
$('#curvyCorners').countdown({until: liftoffTime});

Retrieve the current periods from a countdown timer.

Current periods: Get now

 

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

Highlight last five seconds:   Restart

$('#highlightCountdown').countdown({until: 0,
	onTick: highlightLast5});
	
function highlightLast5(periods) {
	if ($.countdown.periodsToSeconds(periods) == 5) {
		$(this).addClass('highlight');
	}
}

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

In the Wild

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

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
	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
	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.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 

$(selector).countdown('change', settings) // Change instance settings
$(selector).countdown('change', name, value)

$(selector).countdown('settings', 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('getTimes') // Retrieve the current time periods