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.6. 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.
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.
alwaysExpire | compact | compactLabels | description | expiryText | expiryUrl | format | isRTL | labels | labels1 | layout | onExpiry | onTick | serverSync | since | timeSeparator | timezone | until
| Name | Type | Default | Comments |
|---|---|---|---|
| until | Date | 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 | 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. 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. |
| 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. |
| 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. |
| 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. |
| 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. |
change | destroy | getTimes | lap | pause | periodsToSeconds | resume | setDefaults | settings | UTCDate
| 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 +600time (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 +600year (number) is the local yearmonth (number, optional) is the local month (0 to 11)day (number, optional) is the local day in the monthhours (number, optional) is the local hourmins (number, optional) is the local minutesecs (number, optional) is the local secondms (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 namevalue (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 namevar 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. |
Contact Keith Wood at kbwood{at}iinet.com.au with comments or suggestions.