SimplyCountdown.js Documentation

A minimal, zero-dependency countdown tool built with TypeScript support

Installation

npm install simplycountdown.js

yarn add simplycountdown.js

pnpm install simplycountdown.js

bun install simplycountdown.js

Download Options

Install simplyCountdown.js using your preferred package manager (npm, yarn, pnpm, or bun) or download directly from our repository.

Download simplyCountdown.js from GitHub (Free, Open Source)

Why Choose simplyCountdown.js?

Key Benefits

Lightweight: Less than 5KB minified
Easy Integration: Works with any JavaScript project
Customizable: Multiple themes and styling options
Cross-browser Compatible: Works on all modern browsers

A lightweight JavaScript countdown library born from the need for simplicity. Perfect for websites, landing pages, events, and any web project requiring time-based countdowns.

No complexity or dependencies - just add customizable countdown timers quickly. Ideal for developers who need a reliable, performance-focused countdown solution.

Examples

Explore various implementations of simplyCountdown.js below. From basic countdowns to complex customizations, these examples demonstrate the library's versatility. Some examples includes their configuration code and features different themes and options available in simplyCountdown.js.

Default Theme

Without Zero Units - Dark Theme

Inline

Count Up - Cyberpunk Theme

Circle Theme

Losange Theme

Complexe Pluralization - Russian Example

    
    // Example 7: with custom Russian pluralization
    simplyCountdown('#custom-plural', {
        // some parameters...
        words: {
            days: {
                lambda: (root, n) => pluralizeRus(n, 'день', 'дня', 'дней'),
                root: 'день'
            },
            hours: {
                lambda: (root, n) => pluralizeRus(n, 'час', 'часа', 'часов'),
                root: 'час'
            },
            minutes: {
                lambda: (root, n) => pluralizeRus(n, 'минута', 'минуты', 'минут'),
                root: 'минута'
            },
            seconds: {
                lambda: (root, n) => pluralizeRus(n, 'секунда', 'секунды', 'секунд'),
                root: 'секунда'
            }
        }
    });

    function pluralizeRus(number, singular, genitiveSingular, genitivePlural) {
        const lastDigit = number % 10;
        const lastTwoDigits = number % 100;

        if (lastTwoDigits >= 11 && lastTwoDigits <= 14) {
            return `${genitivePlural}`; // Specific case for numbers 11-14
        }

        if (lastDigit === 1 && lastTwoDigits !== 11) {
            return `${singular}`; // Specific case for number (1, 21, 31...)
        }

        if (lastDigit >= 2 && lastDigit <= 4 && !(lastTwoDigits >= 12 && lastTwoDigits <= 14)) {
            return `${genitiveSingular}`; // Genetive singular (2, 3, 4...)
        }

        return `${genitivePlural}`; // Geenetive plural (0, 5, 6...)
    }

Control Example


    // Example 8: With controls
    const controlDemo = simplyCountdown('.simply-countdown-control', {
        year: nextYear,
        month: nextMonth,
        day: 27,
        zeroPad: false,
        enableUtc: true,
        onUpdate: () => {
            updateStateBox(controlDemo.getState());
        },
        onResume: () => {
            updateStateBox(controlDemo.getState());
        },
        onStop: () => {
            updateStateBox(controlDemo.getState());
        }
    });

    const updateStateBox = (state) => {
        let stateBox = document.querySelector('.state-box');
        stateBox.innerHTML = JSON.stringify(state, null, 2);
    }

    updateStateBox(controlDemo.getState());
    // Not a conventional declaration, but it's useful for the demo
    window.controlDemo = controlDemo;

Usage

Javascript - common usage

simplyCountdown.js offers seamless integration for creating dynamic countdown timers in your web projects. Whether you're using ES modules or traditional JavaScript, the library provides a straightforward API to implement countdowns for events, launches, or deadlines. Below are complete examples showing how to initialize and customize your countdown timer with various options and configurations.

Before You Begin

First, create an HTML element that will contain your countdown. This element needs a unique selector (ID or class) that simplyCountdown will target:

<div id="any-id" class="any-class theme-or-custom-theme"></div>

This element will be automatically populated with the countdown timer when initialized.

ES module usage:


    import simplyCountdown from 'simplycountdown.js';

    // This is an example with default parameters
    simplyCountdown('[CSS-SELECTOR]', {
        year: 2015, // Target year (required)
        month: 6, // Target month [1-12] (required)
        day: 28, // Target day [1-31] (required)
        hours: 0, // Target hour [0-23], default: 0
        minutes: 0, // Target minute [0-59], default: 0
        seconds: 0, // Target second [0-59], default: 0
        words: { // Custom labels, with lambda for plurals
            days: { root: 'day', lambda: (root, n) => n > 1 ? root + 's' : root },
            hours: { root: 'hour', lambda: (root, n) => n > 1 ? root + 's' : root },
            minutes: { root: 'minute', lambda: (root, n) => n > 1 ? root + 's' : root },
            seconds: { root: 'second', lambda: (root, n) => n > 1 ? root + 's' : root }
        },
        plural: true, // Use plurals for labels
        inline: false, // Inline format: e.g., "24 days, 4 hours, 2 minutes"
        inlineSeparator: ', ', // Separator for inline format, default: ", "
        inlineClass: 'simply-countdown-inline', // CSS class for inline countdown
        enableUtc: false, // Use UTC time if true
        refresh: 1000, // Refresh interval in ms, default: 1000
        sectionClass: 'simply-section', // CSS class for each countdown section
        amountClass: 'simply-amount', // CSS class for numeric values
        wordClass: 'simply-word', // CSS class for unit labels
        zeroPad: false, // Pad numbers with leading zero
        removeZeroUnits: false, // Remove units with zero value
        countUp: false, // Count up after reaching zero
        onEnd: () => {}, // Callback when countdown ends
        onStop: () => {}, // Callback when countdown is stopped
        onResume: () => {}, // Callback when countdown is resumed
        onUpdate: (params) => {} // Callback when countdown is updated
    });

    // Also, you can init with already existing Javascript Object.
    let myElement = document.querySelector('.my-countdown');
    simplyCountdown(myElement, { /* options */ });

    let multipleElements = document.querySelectorAll('.my-countdown');
    simplyCountdown(multipleElements, { /* options */ });

Accessing TypeScript Source Files:


    import simplyCountdown from "simplycountdown.js/src/core/simplyCountdown";

CommonJS:


    const simplyCountdown = require("simplycountdown.js");

    simplyCountdown("#mycountdown", {
        year: 2025,
        month: 12,
        day: 25,
    });

Browser (UMD):


    <script src="path/to/simplyCountdown.umd.js"></script>
    <script>
        simplyCountdown("#mycountdown", {
            year: 2025,
            month: 12,
            day: 25,
        });
    </script>

Countdown Controller

Control Methods API

Control your countdown timers with precision using the returned controller object. simplyCountdown's API lets you stop, resume, and update countdowns dynamically. Perfect for event scheduling, real-time updates, and interactive applications.

The following methods are available for complete countdown management:


    // Initialize with control callbacks
    const countdown = simplyCountdown('#mycountdown', {
        year: 2025,
        month: 12,
        day: 25,
        onStop: () => console.log('Countdown stopped'),
        onResume: () => console.log('Countdown resumed'),
        onUpdate: (newParams) => console.log('Updated with:', newParams)
    });

    // Control the countdown
    countdown.stopCountdown();    // Pause
    countdown.resumeCountdown();  // Resume
    countdown.updateCountdown({   // Update parameters
        year: 2026,
        month: 1
    });

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

    // Multiple countdowns
    const countdowns = simplyCountdown('.countdown-class', options);
    countdowns.stopCountdown();  // Stops all countdowns
    countdowns.updateCountdown({ year: 2026 }); // Updates all

Available Themes

Countdown Ready-to-use Themes: Default, Dark, Cyberpunk, Circle & Losange Styles

simplyCountdown offers multiple visually appealing themes to enhance your countdown timer's appearance. Each theme is carefully designed to suit different website styles and aesthetics, from minimal to modern designs.

The theme collection includes a clean default style, a sleek dark mode, a futuristic cyberpunk variation, an elegant losange theme, and a modern circle design. These themes are implemented through separate CSS files for optimal performance and easy customization.

To implement any theme, simply include the corresponding CSS file in your HTML document's head section. Each theme maintains the countdown's functionality while providing unique visual presentations that can match your website's design language.

Important Note About Themes

Each theme requires its specific CSS class to be applied. Make sure to use the correct class name when implementing a theme:

Default theme: simply-countdown
Dark theme: simply-countdown-dark
Cyberpunk theme: simply-countdown-cyber
Losange theme: simply-countdown-losange
Circle theme: simply-countdown-circle


    <!-- Choose one or more themes: -->
    <link rel="stylesheet" href="dist/themes/default.css">
    <link rel="stylesheet" href="dist/themes/dark.css">
    <link rel="stylesheet" href="dist/themes/cyber.css">
    <link rel="stylesheet" href="dist/themes/losange.css">
    <link rel="stylesheet" href="dist/themes/circle.css">

    <div class="my-countdown simply-countdown"></div>
    <div class="my-countdown simply-countdown-dark"></div>
    <div class="my-countdown simply-countdown-cyber"></div>
    <div class="my-countdown simply-countdown-losange"></div>
    <div class="my-countdown simply-countdown-circle"></div>

    <script>
    // This will init all countdowns with the same options, but different themes
    simplyCountdown('.my-countdown', {
        year: 2024,
        month: 12,
        day: 25
    });
    </script>

Customize

Create your fully customized Countdowns Themes

Customize your countdown timers with CSS to match your website's design perfectly.

simplyCountdown.js provides a flexible HTML structure that's easy to style. Whether you want minimal designs or elaborate displays, the library's modular structure lets you modify individual elements like numbers, labels, and containers.

Below is the base CSS structure you can customize:


    .custom-countdown-theme {
        /* Main countdown container */
    }

    .custom-countdown-theme > .simply-section {
        /* Individual time unit blocks */
    }

    .custom-countdown-theme > .simply-section > div {
        /* Inner container for amount and word */
    }

    .custom-countdown-theme > .simply-section .simply-amount,
    .custom-countdown-theme > .simply-section .simply-word {
        /* Common styles for numbers and labels */
    }

    .custom-countdown-theme > .simply-section .simply-amount {
        /* Number display */
    }

    .custom-countdown-theme > .simply-section .simply-word {
        /* Label text */
    }

simplyCountdown.js