<p align="center"> <img src="https://img.shields.io/npm/dm/simplycountdown.js.svg?color=449824" alt="NPM Downloads"> <img src="https://img.shields.io/github/package-json/version/VincentLoy/simplycountdown.js" alt="GitHub package.json dynamic"> <img src="https://img.shields.io/npm/l/simplycountdown.js.svg?color=4f46e5" alt="NPM License"> <img src="https://img.shields.io/github/issues/VincentLoy/simplyCountdown.js.svg" alt="GitHub Issues"> <img src="https://img.shields.io/github/issues-pr/VincentLoy/simplyCountdown.js.svg" alt="GitHub PRs"> </p>

SimplyCountdown.js

A simple yet powerful countdown plugin, with no dependencies. Create beautiful countdowns with ease!

Features

• Zero dependencies
• TypeScript support
• Multiple module formats (ES, UMD, CommonJS)
• Multiple themes included
• Lightweight and performant
• Count up or down functionality
• UTC support
• Highly customizable
• Control API (stop, resume, update)
• Comprehensive event callbacks

Installation

npm install simplycountdown.js
# or
yarn add simplycountdown.js
# or
bun install simplycountdown.js

1. Prepare your HTML

<!-- ...YOUR HTML CODE -->
<div class="my-super-countdown simply-countdown-circle"></div>
<!-- YOUR HTML CODE... -->

In this example you will have to target .my-super-countdown and will apply the circle theme.

2. Basic Usage

ES Module

import simplyCountdown from "simplycountdown.js";

simplyCountdown(".my-super-countdown", {
    year: 2025,
    month: 12,
    day: 25,
});

Accessing Source Files

If you want to import and compile the TypeScript source files directly, you can include the source files in your project:

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

CommonJS

const simplyCountdown = require("simplycountdown");

simplyCountdown(".my-super-countdown", {
    year: 2025,
    month: 12,
    day: 25,
});

Browser (UMD)

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

Configuration Options

// .my-super-countdown is an example
// you can target any HTML element with any CSS selector
simplyCountdown(".my-super-countdown", {
    // Target date (Required)
    year: 2025, // Target year [YYYY]
    month: 12, // Target month [1-12]
    day: 25, // Target day [1-31]
    hours: 0, // Target hours [0-23]
    minutes: 0, // Target minutes [0-59]
    seconds: 0, // Target seconds [0-59]

    // Words customization
    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, // Display inline (true) or in blocks (false)
    inlineSeparator: ", ", // Separator for inline display
    enableUtc: false, // Use UTC time instead of local time

    // Styling classes
    inlineClass: "simply-countdown-inline", // Class for inline display
    sectionClass: "simply-section", // Class for each time unit section
    amountClass: "simply-amount", // Class for number display
    wordClass: "simply-word", // Class for word display

    // Formatting options
    zeroPad: false, // Add leading zeros to numbers (e.g., 05 instead of 5)
    countUp: false, // Count up from target date instead of down to it
    removeZeroUnits: false, // Hide time units when they reach zero
    refresh: 1000, // Update interval in milliseconds (1 second = 1000)

    // Event handlers
    onEnd: () => {
        // Callback function when countdown ends
        console.log("Countdown finished!");
    },
    onStop: () => {}, // Callback when countdown is stopped
    onResume: () => {}, // Callback when countdown is resumed
    onUpdate: (params) => {}, // Callback when countdown is updated
});

HTML Structure

The plugin generates the following HTML structure:

Block Display (default)

<div class="simply-countdown">
    <div class="simply-section">
        <div>
            <span class="simply-amount">24</span>
            <span class="simply-word">days</span>
        </div>
    </div>
    <!-- Similar sections for hours, minutes, seconds -->
</div>

Inline Display

<div class="simply-countdown simply-countdown-inline">24 days, 3 hours, 45 minutes, 12 seconds</div>

Themes

The library comes with several built-in themes:

• default.css - Classic theme with clean, modern design
• dark.css - Dark mode theme
• circle.css - Circular display with modern aesthetics
• cyber.css - Cyberpunk-inspired design
• losange.css - Diamond-shaped display

To use a theme, include its CSS file:

<link rel="stylesheet" href="path/to/themes/default.css" />

SimplyCountdown.js includes several pre-built themes to enhance your countdown's appearance. Each theme is designed for different visual styles and use cases.

Available Themes

Note: All themes are available in both standard (.css) and minified (.min.css) formats for production use.

1. Default Theme (dist/themes/default.css)

   • Apply class: simply-countdown
   • Clean, modern design with flat colors

2. Dark Theme (dist/themes/dark.css)

   • Apply class: simply-countdown-dark
   • Sleek dark mode appearance with light text

3. Cyberpunk Theme (dist/themes/cyber.css)

   • Apply class: simply-countdown-cyber
   • Futuristic, neon-inspired design with glowing effects

4. Circle Theme (dist/themes/circle.css)

   • Apply class: simply-countdown-circle
   • Modern circular display with rounded sections

5. Losange Theme (dist/themes/losange.css)

   • Apply class: simply-countdown-losange
   • losange display with rotated sections

Theme Implementation

1. Import Theme CSS

<link rel="stylesheet" href="path/to/themes/default.css" />

2. Apply Theme

Simply include the CSS file in your HTML document, and the theme will be applied automatically to your countdown elements.

Customizing Themes

You can customize any theme by overriding the CSS classes. The base structure for customization is:

.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 */
}

These base classes provide a foundation for creating your own custom themes or modifying existing ones.

Examples

New Year Countdown with UTC

simplyCountdown("#newyear", {
    year: 2025,
    month: 1,
    day: 1,
    enableUtc: true,
    zeroPad: true,
    onEnd: () => {
        alert("Happy New Year!");
    },
});

Event Timer (Count Up) with Zero Padding

simplyCountdown("#timer", {
    year: 2024,
    month: 1,
    day: 1,
    countUp: true,
    zeroPad: true,
    removeZeroUnits: true,
});

Custom Words with Inline Display

simplyCountdown("#inline", {
    year: 2025,
    month: 12,
    day: 25,
    inline: true,
    inlineSeparator: " | ",
    words: {
        days: {
            lambda: (root, count) => (count === 1 ? "day" : "days"),
            root: "day",
        },
        hours: {
            lambda: (root, count) => (count === 1 ? "hour" : "hours"),
            root: "hour",
        },
        minutes: {
            lambda: (root, count) => (count === 1 ? "minute" : "minutes"),
            root: "minute",
        },
        seconds: {
            lambda: (root, count) => (count === 1 ? "second" : "seconds"),
            root: "second",
        },
    },
});

Selector Support

The plugin accepts various selector types:

// CSS selector string
simplyCountdown("#countdown", parameters);

// Single DOM element
simplyCountdown(document.getElementById("countdown"), parameters);

// Multiple elements
simplyCountdown(document.querySelectorAll(".countdown"), parameters);

Control Features

The countdown instance returns a controller object that allows you to manipulate the countdown:

// Initialize countdown
const countdown = simplyCountdown("#mycountdown", parameters);

// Stop the countdown
countdown.pause();

// Resume countdown
countdown.resume();

// Update countdown parameters
countdown.update({
    year: 2026,
    month: 1,
    day: 1,
});

// Chain control methods
countdown.pause();
countdown.resume();
countdown.update({ year: 2026, hours: 12, minutes: 51 });

Development Commands

Main Commands

• npm run dev: Start development server for the documentation site & Core library (port 3000)
• npm run build: Build everything (library, themes, and documentation)
• npm run preview: Preview the documentation site

Build Commands

• npm run build:lib: Build the library (ES and UMD formats)
• npm run build:themes: Build CSS themes
• `n