Countdown timer (above) set to New Years Day.





A countdown widget for your web page that displays the remaining as a flip clock or simple numbers.

The countdown timer can be used two ways:

1. Specify a target date. (year, month, day, hour, minute, second)

2. Specify a total number of seconds to count down "to".

Set it up to use external images (as shown above), or use without images as seen in the examples to the right.

To use countdown, include the following lines of code into your page:

The following goes into your page's <head>
<script src="countdown.js"></script>

The following can go anywhere in the <body>
var myCountdown1 = new Countdown({time:316});

Countdown is a stand-alone javascript program that doesn't require any dependancies such as jquery, motools, prototype or similar.

NOTE: IE8 is not supported, nor will it be. I don't mean to sound pretentious, but… I believe people who use IE8 are either developers testing their wares, or folks who only use the web for "the basics" and are happy with "the basics". Plus, supporting IE8 is detrimental to the growth of the web (link), and restricts the potential available within the overwhelming majority of other browsers.



Version 4.3 (Mar. 12, 2014)




5 minutes


4 Days from now


April 1 @ 4pm


The 15th of next month






There are many more options available, refer to block below, or the "README.txt" in the download package for details on all available options.

// Usage:

// -------------------------------------------------
// Count down to a date
// -------------------------------------------------

var test1 = new Countdown({
                              year : 2013,
                              month : 1,
                              day : 1,
                              hour : 0,
                              ampm : "am",
                              minute : 0,
                              second : 0 // < - no comma on last item!!
// -------------------------------------------------
// Count down number of seconds
// -------------------------------------------------

var test2 = new Countdown( { style: "flip", time: 3600 } );
// -------------------------------------------------
// Advanced Options
// -------------------------------------------------

function countdownComplete(){
var myCD2 = new Countdown({
                         // Using "number of seconds"
                         time   : 15, // Total number of seconds to count down.
                         // --- OR ---
                         // Using a "dead line" date (NOTE: If "time" set this deadline date will NOT be used ("time" over-rides date))

                         year   : 2013,  // (optional) The target date's year
                         month  : 1,     // (optional) The target date's month
                         day    : 1,     // (optional) The target date's day
                         hour   : 0,     // (optional) The target date's hour
                         ampm   : "am",  // (optional) Is the hour refering to AM (early/day) or PM (late/night)?
                         minute : 0,          // (optional) The target date's minutes
                         second : 0,          // (optional) The target date's seconds
                         offset : 0,          // (optional) Number of hours to offset. Can be positive or negative.
                         // ---------------------------------
                         // Optional settings

                         // ---------------------------------
                         hideLabels : false,  // Set to true to hide the text labels
                         hideLine : false,    // When true, hides the black line in the middle of the numbers. (Doesn't affect the "flip" stlye)
                         width    : 200,      // Defaults to 200 x 30 pixels, you can specify a custom size here
                         height   : 30,       //
                         inline   : true,     // If inline, text will wrap around object, otherwise this countdown object will consume the entire "line"
                         target   : "foo",    // A reference to an html DIV id (e.g. DIV id="foo")
                         style    : "boring", // flip boring whatever (only "flip" uses image/animation)
                         rangeHi  : "year",   // The highest unit of time to display
                         rangeLo  : "second", // The lowest unit of time to display
                         padding  : 0.4,             // Padding between the digits and the background box. Value reflects a percentage of overall height.
                         onComplete : countdownComplete, // Specify a function to call when done. The function is pinged with 1 argument,
                                                                                                                          which is a generic object containing the deadline {year, month, day, hour, minute, second, ms}e
                         numberMarginTop : 5.5, // The space on top of the numbers. Used for padding
                         interval : 82,        // Number of milliseconds between display updates. 1000 = 1 second
                         truncate : true,      // Prevents culmination of hidden values into rangeHi. (So you can just chop off at rangeHi)
                         labelText : {
                                       second : "SECONDS",
                                       minute : "MINUTES",
                                       hour   : "HOURS",
                                       day    : "DAYS",
                                       month  : "MONTHS",
                                       year   : "YEARS" // <- no comma on last item!

                         numbers : {
                             font : "Arial",
                             color : "#FFFFFF",
                             bkgd : "#365D8B",
                             rounded : 0.15, // percentage of size
                             shadow : {
                                           x : 0, // x offset (in pixels)
                                           y : 3, // y offset (in pixels)
                                           s : 4, // spread
                                           c : "#000000", // color
                                           a : 0.4 // alpha
                         labels : {
                             font   : "Arial",
                             color  : "#000000",
                             weight : "normal" // < - no comma on last item!


Release Notes

v4.3 Mar. 13, 2014 @ 6:29 pm EST
- Fixed bug: User defined "minute" was not incorporated into calculations.

v4.2 Mar. 6, 2014 @ 6:29 pm EST
- Revereted to my difftime logic library. As it turns out, the other library didn't provide support for combing total days, total months etc. Which means I'd essentially have to incorporate that in anyway. Heavy testing was conducted on my time difference logic, but there may be some quirks for certain difftime scenerios. For example the time between Jan 29th and Apr. 1 is a tricky calculation.
- Added "truncate" option.
- Included "tests.html" for a very small portion of the test-cases (this file is not static, so you can conduct specific tests).
- Note that daylight savings time can cause "what you think" and "reality" to be different.

v4.0 Mar. 6, 2014
- Replaced difftime logic with the datejs javascript library. This provides more accurate values for time differneces between dates including fragmented months, days, hours, minutes and seconds. (I actually spent quite some time developing my own logic, which seemed to work rather well, but after banging on it, there were just too many weirdo instances that didn't add up as expected. So, why re-invent the wheel?)
- Added "interval" option to set each instance's update time independantly.
- Fixed onComplete handling.The onComplete function is now sent 1 argument, which is a generic object containing the deadline year, month, etc.
- Numerous other tweaks, updates and fixes.

v3.3 Feb. 25, 2014
- Fixed cross-month calculation when target date-number = today date-number + 1
- Fixed rounding errors on "time" type countdowns. (e.g. minutes didn't change until < 30 seconds)
- Added option to hide the thin black line for "boring" style countdowns.

v3.1 Feb. 19, 2014
- Added "offset" option, so users can manually apply a time zone offset.
- Included logic to acount for daylight savings.

v3.0 Feb. 18, 2014
- Added "hideLabels" option
- Added "labelText" option
- Fixed concept: When remaining time is larger than rangeHi, the rangeHi now displays the culmination of hidden values. For example, if rangeHi is set to "month" and there are acutally 2 years remaining until the target time, the months value will dispaly the fragment months + an additional 24 months resulting in something similar to: 29. (In the older versions, the year simply wouldn't display, and the months value would be capped at 12). This concept holds true for months, days, hours, minutes and seconds.
- Updated display engine to jbeeb alpha