easy-countdown

Simple, lightweight and easy to use countdown plugin

• no dependencies — jQuery is optional
• you control the markup: rendering is a callback
• written in TypeScript, ships its own types
• ESM + CJS + UMD builds, ~1.2 kB gzipped

Install

npm install easy-countdown

Usage

import { Countdown } from 'easy-countdown';

new Countdown(document.querySelector('.countdown'), {
  date: '2087-06-07T15:03:25Z',
  render(diff) {
    this.el.innerHTML =
      `${this.leadingZeros(diff.hours)}:` +
      `${this.leadingZeros(diff.min)}:` +
      `${this.leadingZeros(diff.sec)}`;
  },
  onEnd() {
    this.el.innerHTML = 'Time is up';
  },
});

It starts automatically. Via a script tag, the UMD bundle exposes a global Countdown:

<script src="node_modules/easy-countdown/dist/countdown.min.js"></script>
<script>
  new Countdown(document.querySelector('.countdown'), { date: '2087-06-07' });
</script>

jQuery

<script src="jquery.js"></script>
<script src="node_modules/easy-countdown/dist/jquery.countdown.min.js"></script>
<script>
  $('.countdown').countdown({ date: '2087-06-07T15:03:25Z' });

  // the instance lives on the element's data
  $('.countdown').data('countdown').update('2099-01-01');

  // tear it down
  $('.countdown').countdown('destroy');
</script>

The plugin never touches the global $, so it works under jQuery.noConflict(). As a module, when jQuery is not a global:

import { registerJQueryPlugin } from 'easy-countdown/jquery';
import $ from 'jquery';

registerJQueryPlugin($);

The date can also come from the element. It wins over the date option, so one call can configure many elements with their own dates — the same ordering 2.x used:

<div class="countdown" data-date="2087-06-07T15:03:25Z"></div>

Dates

Pass a Date, a timestamp, or a string. Prefer ISO 8601 — anything else is parsed inconsistently across browsers. "August 23, 2016 24:00:00" is the classic trap: V8 rolls hour 24 into the next day, Safari rejects it outright.

Values that cannot be parsed now throw rather than silently counting down to zero, which used to be indistinguishable from a finished countdown:

new Countdown(el, { date: 'nonsense' });
// TypeError: countdown: invalid date "nonsense". Prefer an ISO 8601 string …

Options

| Option | Default | Description | | --- | --- | --- | | date | 2087-06-07T15:03:25 | When the countdown reaches zero. Date, string or timestamp | | refresh | 1000 | Re-render interval in ms. 0 renders once and never repeats | | offset | 0 | Milliseconds added to the remaining time, e.g. to correct clock skew | | render | writes a sentence | (diff) => void, called on every tick | | onEnd | — | () => void, called once when the countdown reaches zero |

render and onEnd are bound to the instance, so this.el, this.options, this.running and this.leadingZeros() are available inside them. Arrow functions keep their own this, as usual.

Decimal seconds

leadingZeros takes an optional third argument for decimal places. Only the integer part is padded, so the field width does not jitter as the fraction ticks:

render(diff) {
  this.el.textContent =
    this.leadingZeros(diff.sec + diff.millisec / 1000, 2, 2) + ' sec';
  // "07.35 sec"
}

Pair it with a small refresh — refresh: 50 or so — otherwise the decimals only move once a second.

The diff object

render receives, and getDiffDate() returns:

| Field | Description | | --- | --- | | years days hours min sec | remaining time, each within its own range | | millisec | 0–999 | | total | whole milliseconds remaining; 0 once finished |

API

| Method | Description | | --- | --- | | start() | Start ticking. Idempotent — it will not stack intervals | | stop() | Stop ticking, leaving the last output in place | | restart(options) | Apply new options and start again | | update(date) | Point at a new date and re-render. Call start() afterwards to resume ticking if it had already finished | | updateOffset(ms) | Adjust the offset | | render() | Render once, now | | destroy() | Stop ticking and release the element | | getDiffDate() | The remaining time. Has no side effects | | leadingZeros(num, length?, fractionDigits?) | Pad with zeros; optionally keep decimal places | | running / finished | Getters for the current state | | options / el | The resolved options and the host element |

All methods except destroy() and getDiffDate() return the instance for chaining.

Examples

Run npm run build, then open examples/index.html in a browser.

Migrating from 2.x

• Distributed as ESM (dist/countdown.mjs), CommonJS (dist/countdown.cjs) and a minified UMD bundle for script tags (dist/countdown.min.js). The UMD global is still Countdown. The npm package is still easy-countdown.
• Bower packaging was removed. Install from npm.
• Licensing is MIT only. The 2.x manifest claimed MIT and GPL, with no LICENSE file in the repo.
• getDiffDate() no longer fires onEnd as a side effect of being read. render() owns that now, so inspecting the remaining time is safe.
• millisec is now 0–999. It used to be a fraction of a second times 1000.
• The diff object gained total.
• Invalid dates throw instead of rendering zeros.
• leadingZeros gained a third argument for decimal places.
• New: destroy(), finished, running, and TypeScript types.
• The build output moved to dist/. The 2.x dest/ filenames are still published as copies, so existing CDN and <script src> URLs keep working.

Fixed in 3.0

• onEnd never fired when the target date was already in the past, or when refresh was 0 — it was gated on an interval already running.
• restart() did not clear the running interval, leaking a timer on each call and multiplying the render rate.
• sec could render as 60 just under a minute, because it was rounded rather than floored.
• The jQuery plugin used the global $ internally and broke under jQuery.noConflict().
• new Countdown(el) and $el.countdown() threw when no options were given.

License

MIT