Tiny jQuery-Compatible Countdown JavaScript Library - simplyCountdown.js

simplyCountdown.js is a dead simple JavaScript library used to create a highly configurable and styleable countdown/countup timer for your coming soon / under construction page. Also can be used as a plugin for your jQuery project.

Install & Download:

# Yarn
$ yarn add simplycountdown

# NPM
$ npm install simplycountdown

# BUN
$ bun add simplycountdown

How to use it:

1. Import the simplyCountdown.js into your web project.

// ES Module
import simplyCountdown from "simplycountdown.js";

// CommonJS
const simplyCountdown = require("simplycountdown");

2. Or load the UMD version of simplyCountdown.js in your html page.

<script src="/path/to/simplyCountdown.umd.js"></script>

3. Load a theme CSS of your choice in the head section of the html page.

<link href="/themes/default.min.css" rel="stylesheet">
<link href="/themes/circle.min.css" rel="stylesheet">
<link href="/themes/cyber.min.css" rel="stylesheet">
<link href="/themes/dark.min.css" rel="stylesheet">
<link href="/themes/losange.min.css" rel="stylesheet">

4. Create a simple countdown timer with default theme.

<h2>Default</h2>
<div class="simply-countdown"></div>
<h2>Circle</h2>
<div class="simply-countdown-circle"></div>
<h2>Cyber</h2>
<div class="simply-countdown-cyber"></div>
<h2>Dark</h2>
<div class="simply-countdown-dark"></div>
<h2>Losange</h2>
<div class="simply-countdown-losange"></div>

simplyCountdown('.simply-countdown', {

  year: 2025, // required
  month: 6, // required
  day: 30, // required
  /* More Options here */
  
});

5. You can add your own themes in the CSS.

.simply-countdown {
    /* The countdown */
}
.simply-countdown > .simply-section {
    /* coutndown blocks */
}

.simply-countdown > .simply-section > div {
    /* countdown block inner div */
}

.simply-countdown > .simply-section .simply-amount,
.simply-countdown > .simply-section .simply-word {
    /* amounts and words */
}

.simply-countdown > .simply-section .simply-amount {
    /* amounts */
}

.simply-countdown > .simply-section .simply-word {
    /* words */
}

6. Default options and event handlers.

simplyCountdown(".simply-countdown", {
  // Required)
  year: 2025, // [YYYY]
  month: 12, // [MM]
  day: 25, // [1-31]
  hours: 0, // [0-23]
  minutes: 0, // [0-59]
  seconds: 0, // [0-59]

  // Customize slots
  words: {
    days: {
      // Function to handle pluralization
      lambda: (root, count) => (count > 1 ? root + "s" : root),
      root: "day", // Base word for days
    },
    hours: {
      lambda: (root, count) => (count > 1 ? root + "s" : root),
      root: "hour",
    },
    minutes: {
      lambda: (root, count) => (count > 1 ? root + "s" : root),
      root: "minute",
    },
    seconds: {
      lambda: (root, count) => (count > 1 ? root + "s" : root),
      root: "second",
    },
  },

  // Display options
  plural: true, // Enable/disable pluralization
  inline: false,
  inlineSeparator: ", ",
  enableUtc: false,

  // Styling classes
  inlineClass: "simply-countdown-inline",
  sectionClass: "simply-section", 
  amountClass: "simply-amount", 
  wordClass: "simply-word", 

  // Formatting options
  zeroPad: false, // Add leading zeros to numbers (e.g., 05 instead of 5)
  countUp: false,
  removeZeroUnits: false,
  refresh: 1000, // 1000 = 1 second 

  // Event handlers
  onEnd: () => {}
  onStop: () => {},
  onResume: () => {}, 
  onUpdate: (params) => {},
  
});

7. API methods.

const myCountdown = simplyCountdown('.simply-countdown', {

  year: 2025, // required
  month: 6, // required
  day: 30, // required
  /* More Options here */
  
});

// Pause
myCountdown.stopCountdown();    

// Resume
myCountdown.resumeCountdown();  

// Update parameters
myCountdown.updateCountdown({   
  year: 2035,
  month: 1
});

// Get the current state
const state = myCountdown.getState();
console.log('Is paused:', state.isPaused);
console.log('Target date:', state.targetDate);

Changelog:

v3.0.0 (2024-12-31)

• jQuery is no longer supported in simplyCountdown to reduce dependencies and improve performance. 
• Updated demo and doc.

v2.0.1 (2024-12-06)

• fix plurals in a generic way
• Added the inlineSeparator parameter. 
• Fix potential UTC-related issues

v1.7.0 (2020-12-04)

• Add Javascript HTML elements support

v1.6.1 (2020-11-26)

• Add more languages support for plural words

v1.5.0 (2019-04-24)

• Add countup support

v1.4.0 (2018-11-28)

• Remove bower support
• migrate from LESS to SASS (scss) / for demo and themes
• migrate lib from ES5 to a really basic ES6

2016-06-05

• bugfix

2015-09-06

• code clean

2015-08-29

• Add UTC support

2015-07-05

• Remove ID Only compatibility

2015-07-03

• Add hours, minutes, seconds in available settings to set the target Date

---

This awesome jQuery plugin is developed by VincentLoy. For more Advanced Usages, please check the demo page or visit the official website.