simplycountdown.js

The simplyCountdown function accepts a selector (string, DOM element, or NodeList) and a configuration object.

Target Date (Required)

• year: Target year [YYYY]
• month: Target month [1-12]
• day: Target day [1-31]
• hours: Target hours [0-23]
• minutes: Target minutes [0-59]
• seconds: Target seconds [0-59]

Words Customization

• words: An object containing days, hours, minutes, and seconds. Each contains a root (string) and a lambda function (root, count) => string to handle pluralization.

Display Options

• plural: Boolean. Enable/disable pluralization.
• inline: Boolean. If true, displays in a single line; if false, displays in blocks.
• inlineSeparator: String. Separator used when inline is true.
• enableUtc: Boolean. Use UTC time instead of local time.
• zeroPad: Boolean. Add leading zeros to numbers (e.g., 05 instead of 5).
• countUp: Boolean. Count up from target date instead of down to it.
• removeZeroUnits: Boolean. Hide time units when they reach zero.
• refresh: Number. Update interval in milliseconds.

Styling Classes

• inlineClass: Class for inline display.
• sectionClass: Class for each time unit section.
• amountClass: Class for number display.
• wordClass: Class for word display.

Event Handlers

• onEnd: Callback when countdown ends.
• onStop: Callback when countdown is stopped.
• onResume: Callback when countdown is resumed.
• onUpdate: Callback when countdown is updated.

simplyCountdown(".my-super-countdown", {
    year: 2025,
    month: 12,
    day: 25,
    words: {
        days: {
            lambda: (root, count) => (count > 1 ? root + "s" : root),
            root: "day",
        },
        // ... other words
    },
    plural: true,
    inline: false,
    enableUtc: false,
    zeroPad: false,
    countUp: false,
    refresh: 1000,
    onEnd: () => {
        console.log("Countdown finished!");
    }
});

The CountdownParameters interface defines the configuration for a countdown instance. It controls the target date, formatting (words, pluralization, inline display), styling (CSS classes), and lifecycle callbacks.

Key configuration groups include:

• Target Date: year, month, day, hours, minutes, seconds.
• Word Formatting: The words object allows customizing how time units are labeled using WordConfig (providing a root string and a lambda function for pluralization logic).
• Display Styles: inline (boolean), inlineSeparator (string), zeroPad (boolean), and various CSS class overrides like inlineClass, sectionClass, amountClass, and wordClass.
• Lifecycle Callbacks: onEnd (required), onStop, onResume, and onUpdate (receives Partial<CountdownParameters>).

const params: CountdownParameters = {
  year: 2025,
  month: 12,
  day: 25,
  hours: 0,
  minutes: 0,
  seconds: 0,
  words: {
    days: { root: 'day', lambda: (root, n) => n === 1 ? root : `${root}s` },
    hours: { root: 'hour', lambda: (root, n) => n === 1 ? root : `${root}s` },
    minutes: { root: 'minute', lambda: (root, n) => n === 1 ? root : `${root}s` },
    seconds: { root: 'second', lambda: (root, n) => n === 1 ? root : `${root}s` }
  },
  plural: true,
  inline: false,
  enableUtc: false,
  onEnd: () => console.log('Countdown finished!')
};

The CountdownController interface provides methods to programmatically manage a running countdown. If you initialize multiple countdowns, you may receive a CountdownControllerArray which extends the standard array with collective control methods.

Available methods:

• stopCountdown(): Pauses the countdown.
• resumeCountdown(): Resumes a paused countdown.
• updateCountdown(newParams: Partial<CountdownParameters>): Updates the countdown configuration (e.g., changing the target date) without a full restart.
• getState(): Returns the current CountdownState, including isPaused, the active interval ID, and the targetDate.

// Assuming 'controller' is an instance of CountdownController
controller.stopCountdown();

const state = controller.getState();
console.log(state.isPaused); // true

controller.updateCountdown({ year: 2026 });
controller.resumeCountdown();