Instance Settings

A separate countdown instance is created for each targetted division or span:

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

Each instance may have different settings, e.g.

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

Below are the options that may be applied to each countdown instance.

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).datepick({minDate: new Date(2014, 12-1, 25)});

alwaysExpire | compact | compactLabels | description | digits | expiryText | expiryUrl | format | isRTL | labels | labels1 | layout | onExpiry | onTick | padZeroes | serverSync | significant | since | tickInterval | timeSeparator | timezone | until | whichLabels

NameTypeDefaultComments
untilDate or string or numbernull Set the time at which the countdown expires. This may be an absolute date, e.g. new Date(2010, 1 - 1, 1), or a value relative to the current time. Provide a numeric value to offset by that many seconds, e.g. +300, or a string value to indicate both the type of units and the amount, e.g. '+2d'. Use 'y' for years, 'o' for months, 'w' for weeks, 'd' for days, 'h' for hours, 'm' for minutes, or 's' for seconds. Upper or lower case characters may be used. Multiple offsets may be combined into one setting, e.g. '+2h +30m'. When providing an actual date you can use the UTCDate function or the timezone setting to take account of a different timezone for the expiry.

One of since or this setting should always be supplied. The countdown displays zeros if this time has passed.

$(selector).countdown({
	until: new Date(2012, 8 - 1, 8)});
$(selector).countdown({
	until: $.countdown.UTCDate(+10, 2012, 1 - 1, 26)});
$(selector).countdown({until: +600});
$(selector).countdown({until: '+1m -1d'});

Since 1.2.1 - setting as a relative value.
sinceDate or string or numbernull Set the time from which the countdown counts up. This may be an absolute date or a value relative to the current time (see until for more information).

One of until or this setting should always be supplied. If both are provided, since has priority. The countdown displays zeros if this time has not yet arrived. The onExpiry event is never triggered.

$(selector).countdown({
	since: new Date(2008, 8 - 1, 8)});
$(selector).countdown({
	since: $.countdown.UTCDate(+10, 2009, 1 - 1, 26)});
$(selector).countdown({since: -600});
$(selector).countdown({since: '-1m +1d'});

Since 1.2.0.
Since 1.2.1 - setting as a relative value.
timezonenumbernull Set the time zone offset from GMT, either as hours or minutes, for the countdown/up. For example, a target time in Sydney, Australia, would have a value of +10 or +600. If not specified no offset is applied. Alternately, use the UTCDate function to set the target time directly.

$(selector).countdown({
	until: new Date(2012, 8 - 1, 8), timezone: +10});

Since 1.5.1 - replaces serverTime.
serverSyncfunctionnull Synchronise the client's time with that of the server by providing a function that returns the current server date and time. This date and time should take into account the server's timezone and any difference between that time and the client's is applied to the countdown when it is started or changed.

Note that this function is only called once per server and the value is cached and used for all subsequent countdowns for that server.

The following example uses a PHP program on the server to return the current server time in a format that can be used directly by the JavaScript callback. You should make sure that your server call is synchronous.

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

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
$now = new DateTime();
echo $now->format("M j, Y H:i:s O")."\n";
?>

Since 1.5.4.
Since 1.5.7 - only called once.
formatstring'dHMS' The format for the countdown display. Use the following characters (in order) to indicate which periods you want to display: '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 mandatory periods, or the corresponding lower-case characters for optional periods, i.e. only display if non-zero. Once one optional period is shown, all the ones after that are also shown.

The default format indicates that days is the maximum unit to display, and then only if non-zero, and always show hours, minutes, and seconds.

If not showing seconds, any left overs cause the next level up to be rounded up (if counting down), meaning that ultimately the countdown shows '1' for that level throughout the last period.

Since 1.1.0 - prior to this you used the showDays ('always' | 'never' | 'asNeeded') and showSeconds (boolean) settings.
Since 1.5.5 - rounding up.
padZeroesbooleanfalse Set to true to pad values with zeroes for a minimum of two digits.

Since 2.0.0.
layoutstring'' A 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 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.

Leave as blank to use the built-in layouts.

$(selector).countdown({layout:'<b>{d<}{dn} {dl} and {d>}'+
	'{hn} {hl}, {mn} {ml}, {sn} {sl}</b>'});

Since 1.4.0.
Since 1.5.0 - refactored to use '{pv}' notation.
Since 1.5.3 - added desc, sep, pnnn, and pd substitutions.
Since 1.5.5 - added p1000 substitutions.
compactbooleanfalse Indicate whether or not the countdown should be displayed in a compact format.
significantnumber0 The number of significant (non-zero) periods to show, or zero for all. For example, if the current period values are 1 month, 0 days, 5 hours, and 23 minutes, a value of 1 would only show the month value, while a value of 2 would show the month and hours values. Note that this doesn't affect compact countdowns, other than to zero out periods past the significant setting. When combined with a custom layout, you must use the '{p<}...{p>}' construct to suppress insignificant sections.

Since 1.5.8.
labelsstring[7] ['Years', 'Months', 'Weeks', 'Days', 'Hours', 'Minutes', 'Seconds'] The display text for the various parts of the countdown. This is one of the regional settings fields.

You can also specify additional labelsn attributes, where n is a number, to handle specialised plural terms for that number, such as those found in Slavic languages for the numbers 2 to 4.

Since 1.1.0 - prior to this it only contained 'Days' to 'Seconds'.
Since 1.4.2 - additional labelsn settings.
labels1string[7] ['Year', 'Month', 'Week', 'Day', 'Hour', 'Minute', 'Second'] The display text for the various parts of the countdown if there is only one of them. This is one of the regional settings fields.

Since 1.2.1 - originally labelsSingle.
Since 1.4.2 - replacing labelsSingle.
compactLabelsstring[4]['y', 'm', 'w', 'd'] The display text for the years, months, weeks, and days in the compact format. This is one of the regional settings fields.

You can also specify additional compactLabelsn attributes, where n is a number, to handle specialised plural terms for that number, such as those found in Slavic languages for the numbers 2 to 4.

Since 1.1.0 - prior to this you used the compactDays (String) setting.
Since 1.4.2 - additional compactLabelsn settings.
whichLabelsfunctionnull Determine which set of labels to use for a given period amount. The default mapping (when this option is null) is to use labelsn, where n is the amount, if available, and labels if not. Some languages have a more complicated plural form that does not easily fit this pattern. For example, Polish uses one form for the value one, a second form for values two to four, 22 to 24, 32 to 34, etc., and a third form for the rest. The function takes the amount as a parameter and returns the n value used above to locate the relevant labels, or zero to use the defaults.

$(selector).countdown({until: liftoffTime,
	labels: ['Yr', 'Mo', 'Wk', 'Dy', 'Hr', 'Mn', 'Sc'],
	labels1: ['Yr1', 'Mo1', 'Wk1', 'Dy1', 'Hr1', 'Mn1', 'Sc1'],
	labels2: ['Yr2', 'Mo2', 'Wk2', 'Dy2', 'Hr2', 'Mn2', 'Sc2'],
	whichLabels: function(amount) {
		var units = amount % 10;
		var tens = Math.floor(amount % 100 / 10);
		return (amount === 1 ? 1 :
			(units >=2 && units <= 4 && tens !== 1 ? 2 : 0));
	}});

Since 1.5.8.
digitsstring[] ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] The strings to use to represent the numeric digits. This is one of the regional settings fields.

$(selector).countdown({until: liftoffTime,
	digits: ['०', '१', '२', '३', '४', '५', '६', '७', '८', '९']});

Since 1.6.0.
timeSeparatorstring':' The separator between the various parts of the countdown time in the compact format. This is one of the regional settings fields.
isRTLbooleanfalse Set to true for languages that read right-to-left, or false for left-to-right. This is one of the regional settings fields.

Since 1.4.2.
descriptionstring'' The descriptive text shown below the countdown timer. This value can contain HTML markup.
expiryTextstring'' A message to display when the countdown reaches zero, replacing the countdown periods. It may contain HTML markup.
Since 1.5.2.
expiryUrlstring'' A URL to load when the countdown reaches zero, replacing the current page.

Since 1.1.0.
alwaysExpirebooleanfalse If true, the onExpiry event is triggered even when the counter starts after the target time. If false, the event only triggers if the counter actively times out.

Since 1.2.1.
onExpiryfunctionnull A callback function that is invoked when the countdown reaches zero. Within the function this refers to the division that holds the widget. No parameters are passed in. Use the expiryText or expiryUrl settings for basic functionality on expiry.

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

function liftOff() {
	alert('We have lift off!');
}
onTickfunctionnull A callback function that is invoked each time the countdown updates itself. Within the function this refers to the division that holds the widget. The array of current countdown periods (int[7] - based on the format setting) is passed as a parameter: [0] is years, [1] is months, [2] is weeks, [3] is days, [4] is hours, [5] is minutes, and [6] is seconds.

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

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

Since 1.1.0 - prior to this only days through to seconds were passed as the parameter.
tickIntervalnumber1 Set the interval in seconds between callbacks to the onTick function. Note that the period resolution is limited to the minimum value displayed in your format. So, if you are not showing seconds, you should only use intervals that are multiples of a minute (60).

$(selector).countdown({
	until: new Date(2012, 8 - 1, 8),
	onTick: updateEvery10Secs: tickInterval: 10});

Since 1.5.7.
Global Settings
NameTypeDefaultComments
regionalOptionsobject[] The set of regional settings for the countdowns. Entries are indexed by the country/region code with '' providing the default (English) settings. Each entry is an object with the following properties: labels, labels1, compactLabels, whichLabels, digits, timeSeparator, and isRTL. Also include any specialised number terms of the form labelsn or compactLabelsn.

Language packages load new entries into this array and automatically apply them as global defaults. If necessary, you can then revert to the default language settings with

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

and apply the language settings to individual fields with

$('#frenchCountdown').countdown($.countdown.regionalOptions['fr']);

Check out the list of available localisation packages.

Since 2.0.0 - previously called regional.
noRequestAnimationFrameboolean Set this jQuery attribute before loading the countdown plugin to prevent the use of the browser's requestAnimationFrame functionality. The countdown then falls back to using setInterval instead.

<script type="text/javascript">
$.noRequestAnimationFrame = true;
</script>
<script type="text/javascript" src="js/jquery.countdown.js"></script>
Functions

destroy | getTimes | lap | option (get) | option (set) | pause | periodsToSeconds | resume | resync | setDefaults | toggle | toggleLap | UTCDate

SignatureReturnsComments
$.countdown.setDefaults(settings)- Update the default instance settings to use with all countdown instances.
$.countdown.UTCDate(tz, time)Date Convert a time to its equivalent UTC time.

tz (number) is the timezone offset, either in hours or minutes, from GMT, for example, Brisbane, Australia, would be +10 or +600

time (Date) is the local date/time

$(selector).countdown({
	until: $.countdown.UTCDate(-8, liftoffTime)});

Since 1.5.1.
$.countdown.UTCDate(tz, year, month, day, hours, mins, secs, ms)Date Convert a time to its equivalent UTC time.

tz (number) is the timezone offset, either in hours or minutes, from GMT, for example, Brisbane, Australia, would be +10 or +600

year (number) is the local year

month (number, optional) is the local month (0 to 11)

day (number, optional) is the local day in the month

hours (number, optional) is the local hour

mins (number, optional) is the local minute

secs (number, optional) is the local second

ms (number, optional) is the local millisecond

$(selector).countdown({until:
	$.countdown.UTCDate(-480, 2010, 1-1, 26, 11, 30, 0, 0)});

Since 1.5.1.
$.countdown.periodsToSeconds(periods)number Convert a set of periods to its equivalent number of seconds. For periods including years or months the number of seconds is averaged.

periods (number[7]) is the number of periods per year/month/week/day/hour/minute/second

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

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

Since 1.5.6.
$.countdown.resync()- Scan all countdown instances and re-synchronise them with the server if they have a serverSync callback.

$.countdown.resync();

Since 2.0.2.
$(selector).countdown('option', options)jQuery object Update the settings for the countdown instance(s) attached to the given division(s).

options (object) the collection of new settings.

$(selector).countdown('option',
	{format: 'hMS', description: 'Until the end'});

Since 1.6.0 - previously you used the 'change' command.
$(selector).countdown('option', name, value)jQuery object Update a particular setting for the countdown instance(s) attached to the given division(s).

name (string) the name of the setting to change;
value (any) the new value of that setting.

$(selector).countdown('option', 'format', 'hMS');

Since 1.5.0.
Since 1.6.0 - previously you used the 'change' command.
$(selector).countdown('option', name)object or any Retrieve one or all of the current settings for the first countdown instance attached to the given division(s).

name (string, optional) the name of the setting to retrieve; omit for all settings.

var settings = $(selector).countdown('option');
var format = $(selector).countdown('option', 'format');

Since 1.5.5.
Since 1.6.0 - previously you used the 'settings' command.
$(selector).countdown('destroy')jQuery object Remove the countdown functionality from the given division(s).
$(selector).countdown('pause')jQuery object Pause the countdown for the given division(s) and allow it to be resumed from that point at a later time. No onTick or onExpiry events are triggered while the countdown is paused.

Since 1.3.0.
$(selector).countdown('lap')jQuery object Pause the countdown display for the given division(s) but continue to process it in the background, similar to pressing the lap-time button on a stopwatch.

Since 1.3.0.
$(selector).countdown('resume')jQuery object Resume the previously paused or lap-time countdown for the given division(s).

Since 1.3.0.
$(selector).countdown('toggle')jQuery object Toggle between the pause and resume commands.

Since 2.0.0.
$(selector).countdown('toggleLap')jQuery object Toggle between the lap and resume commands.

Since 2.0.0.
$(selector).countdown('getTimes')number[7] Retrieve the set of current periods for the first countdown division selected. The entries are for years, months, weeks, days, hours, minutes, and seconds, as determined by the format for the countdown.

var periods = $(selector).countdown('getTimes');

Since 1.3.0.