jQuery Countdown Reference

A jQuery plugin that sets a division or span to show a countdown to a given time. If you find this plugin useful please vote for it on the jQuery site.

This page provides a documentation reference for working with the plugin v1.5.11. See a demonstration of the countdown plugin and download the code from there. Or see a minimal page that you could use as a basis for your own investigations.

Settings
Globals

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

$(selector).datepick({minDate: new Date(2010, 12-1, 25)});

Name	Type	Default	Comments
until	Date or string or number	null	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.
since	Date or string or number	null	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.
timezone	number	null	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`.
serverSync	function	null	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.
format	string	'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.
layout	string	''	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.
compact	boolean	false	Indicate whether or not the countdown should be displayed in a compact format.
significant	number	0	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.
labels	string[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.
labels1	string[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`.
compactLabels	string[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.
whichLabels	function	null	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.
timeSeparator	string	':'	The separator between the various parts of the countdown time in the compact format. This is one of the regional settings fields.
isRTL	boolean	false	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.
description	string	''	The descriptive text shown below the countdown timer. This value can contain HTML markup.
expiryText	string	''	A message to display when the countdown reaches zero, replacing the countdown periods. It may contain HTML markup. Since 1.5.2.
expiryUrl	string	''	A URL to load when the countdown reaches zero, replacing the current page. Since 1.1.0.
alwaysExpire	boolean	false	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.
onExpiry	function	null	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!'); }`
onTick	function	null	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.
tickInterval	number	1	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

Name Type Default Comments

Name	Type	Default	Comments
regional	object[]		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`, `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.regional['']);` and apply the language settings to individual fields with `$('#frenchCountdown').countdown($.countdown.regional['fr']);` Check out the list of available localisation packages.

regional

object[]

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, 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.regional['']);

and apply the language settings to individual fields with

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

Check out the list of available localisation packages.

Functions

Signature	Returns	Comments
$.countdown.setDefaults(settings)	void	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.
$(selector).countdown('change', settings)	jQuery object	Update the settings for the countdown instance(s) attached to the given division(s). `settings` (object) is the set of new options. `$(selector).countdown('change', {description: 'Until the end'});`
$(selector).countdown('change', name, value)	jQuery object	Update one setting for the countdown instance(s) attached to the given division(s). `name` (string) is the property name `value` (any) is the property value `$(selector).countdown('change', description, 'Until the end');` Since 1.5.0.
$(selector).countdown('settings', name)	any	Retrieve one or all settings for the countdown instance attached to the given division. If a name is provided just that property value is returned. Use a name of 'all' for all of the instance settings as an object. If no name is given all the default settings for all instances are returned as an object. `name` (string, optional) is the property name `var settings = $(selector).countdown('settings', 'all');` Since 1.5.5.
$(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('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.