A countdown timer is one of those projects that teaches you a surprising amount. It covers working with dates, interval timing, DOM manipulation, and the kind of edge case handling that makes the difference between a timer that works and one that breaks at midnight on New Year’s Eve.
Let’s build one from scratch — starting simple and adding everything that makes it production-ready.
What We’re Building
A countdown timer that:
- Accepts a target date and time
- Displays days, hours, minutes, and seconds remaining
- Updates every second
- Stops cleanly when it reaches zero
- Handles the case where the target date has already passed
The Core Concept
JavaScript’s Date object gives you the current time in milliseconds since January 1, 1970. The trick is subtracting the current time from the target time to get the difference in milliseconds, then converting that into days, hours, minutes, and seconds.
const target = new Date("2027-12-31T00:00:00");
const now = new Date();
const difference = target - now; // milliseconds remaining
Once you have the difference in milliseconds, the math to extract each unit is straightforward:
const days = Math.floor(difference / (1000 * 60 * 60 * 24));
const hours = Math.floor((difference % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
const minutes = Math.floor((difference % (1000 * 60 * 60)) / (1000 * 60));
const seconds = Math.floor((difference % (1000 * 60)) / 1000);
Each unit uses the modulo operator % to extract only the remaining time after the larger units have been accounted for.
Step 1: The HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Countdown Timer</title>
<link rel="stylesheet" href="style.css" />
</head>
<body>
<div class="countdown-wrapper">
<h1>New Year Countdown</h1>
<div class="timer">
<div class="time-block">
<span id="days">00</span>
<label>Days</label>
</div>
<div class="time-block">
<span id="hours">00</span>
<label>Hours</label>
</div>
<div class="time-block">
<span id="minutes">00</span>
<label>Minutes</label>
</div>
<div class="time-block">
<span id="seconds">00</span>
<label>Seconds</label>
</div>
</div>
<p id="message" class="hidden">Time's up!</p>
</div>
<script src="timer.js"></script>
</body>
</html>
Step 2: The CSS
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
background: #0f172a;
font-family: "Segoe UI", sans-serif;
color: #fff;
}
.countdown-wrapper {
text-align: center;
}
h1 {
font-size: 2rem;
margin-bottom: 40px;
color: #94a3b8;
letter-spacing: 2px;
text-transform: uppercase;
}
.timer {
display: flex;
gap: 20px;
justify-content: center;
}
.time-block {
background: #1e293b;
border-radius: 12px;
padding: 30px 24px;
min-width: 100px;
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
}
.time-block span {
display: block;
font-size: 3.5rem;
font-weight: 700;
color: #38bdf8;
line-height: 1;
margin-bottom: 8px;
}
.time-block label {
font-size: 0.75rem;
text-transform: uppercase;
letter-spacing: 2px;
color: #64748b;
}
#message {
margin-top: 40px;
font-size: 1.5rem;
color: #38bdf8;
}
.hidden {
display: none;
}
Step 3: The JavaScript
// Set your target date here
const TARGET_DATE = new Date("2028-01-01T00:00:00");
// Get DOM elements
const daysEl = document.getElementById("days");
const hoursEl = document.getElementById("hours");
const minutesEl = document.getElementById("minutes");
const secondsEl = document.getElementById("seconds");
const messageEl = document.getElementById("message");
const timerEl = document.querySelector(".timer");
function pad(num) {
return String(num).padStart(2, "0");
}
function updateTimer() {
const now = new Date();
const difference = TARGET_DATE - now;
// If the target date has passed
if (difference <= 0) {
daysEl.textContent = "00";
hoursEl.textContent = "00";
minutesEl.textContent = "00";
secondsEl.textContent = "00";
timerEl.style.opacity = "0.4";
messageEl.classList.remove("hidden");
clearInterval(intervalId);
return;
}
const days = Math.floor(difference / (1000 * 60 * 60 * 24));
const hours = Math.floor((difference % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
const minutes = Math.floor((difference % (1000 * 60 * 60)) / (1000 * 60));
const seconds = Math.floor((difference % (1000 * 60)) / 1000);
daysEl.textContent = pad(days);
hoursEl.textContent = pad(hours);
minutesEl.textContent = pad(minutes);
secondsEl.textContent = pad(seconds);
}
// Run immediately so there's no 1-second delay on load
updateTimer();
// Then update every second
const intervalId = setInterval(updateTimer, 1000);
Paste these three files into a folder, open index.html in a browser, and you have a working countdown timer.
How the Code Works
TARGET_DATE is the only thing you need to change for different use cases. Set it to any future date and time.
pad() adds a leading zero to single-digit numbers. "5" becomes "05". Without this, the timer looks inconsistent when seconds or minutes drop below 10.
updateTimer() runs on load and every second after. The first call ensures the timer shows immediately rather than waiting a full second before displaying.
clearInterval(intervalId) stops the timer cleanly when the countdown reaches zero. Without this, the function keeps running and checking the difference every second indefinitely.
The intervalId variable is declared with const after the first updateTimer() call — this works because JavaScript hoists the intervalId reference, so by the time the interval fires and clearInterval is called inside updateTimer(), the variable is already assigned.
Making It Reusable
Here is a cleaner, class-based version you can use multiple times on the same page:
class CountdownTimer {
constructor(targetDate, elements) {
this.target = new Date(targetDate);
this.elements = elements;
this.intervalId = null;
}
pad(num) {
return String(num).padStart(2, "0");
}
update() {
const difference = this.target - new Date();
if (difference <= 0) {
this.stop();
if (this.elements.message) {
this.elements.message.classList.remove("hidden");
}
return;
}
const days = Math.floor(difference / (1000 * 60 * 60 * 24));
const hours = Math.floor((difference % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
const minutes = Math.floor((difference % (1000 * 60 * 60)) / (1000 * 60));
const seconds = Math.floor((difference % (1000 * 60)) / 1000);
if (this.elements.days) this.elements.days.textContent = this.pad(days);
if (this.elements.hours) this.elements.hours.textContent = this.pad(hours);
if (this.elements.minutes) this.elements.minutes.textContent = this.pad(minutes);
if (this.elements.seconds) this.elements.seconds.textContent = this.pad(seconds);
}
start() {
this.update();
this.intervalId = setInterval(() => this.update(), 1000);
return this;
}
stop() {
clearInterval(this.intervalId);
return this;
}
}
// Usage
const timer = new CountdownTimer("2028-01-01T00:00:00", {
days: document.getElementById("days"),
hours: document.getElementById("hours"),
minutes: document.getElementById("minutes"),
seconds: document.getElementById("seconds"),
message: document.getElementById("message"),
});
timer.start();
This version is cleanly encapsulated. Multiple timers can run independently on the same page, each with its own target date and DOM elements.
Adding a Flip Animation
To make the seconds feel more dynamic, add a brief CSS animation whenever the value changes:
@keyframes flip {
0% { transform: translateY(-10px); opacity: 0; }
100% { transform: translateY(0); opacity: 1; }
}
.flip {
animation: flip 0.3s ease;
}
Then trigger it in JavaScript by adding and removing the class:
function animateElement(el) {
el.classList.remove("flip");
void el.offsetWidth; // Trigger reflow to restart animation
el.classList.add("flip");
}
Call animateElement(secondsEl) inside updateTimer() every time the seconds change. The void el.offsetWidth line forces the browser to re-evaluate the element’s layout, which resets the animation so it plays even if the class was already present.
Handling Time Zones
new Date("2028-01-01T00:00:00") without a time zone suffix is interpreted in the local time of whoever opens the page. If you want the countdown to target a specific absolute moment regardless of the visitor’s location, use UTC:
// Targets midnight UTC — same moment for everyone
const TARGET_DATE = new Date("2028-01-01T00:00:00Z");
// Or specify an offset explicitly
const TARGET_DATE = new Date("2028-01-01T00:00:00-05:00"); // Midnight Eastern
The Z suffix means UTC. An offset like -05:00 specifies hours behind UTC. For events tied to a specific physical location — a product launch, a concert, a New Year’s celebration in a particular city — the explicit offset is the right approach.
Common Issues and Fixes
Timer shows negative numbers — The target date has already passed. Add the difference <= 0 check at the top of updateTimer() and handle it before the math runs.
One-second delay on load — Call updateTimer() once before starting the interval. The interval alone waits a full second before the first execution.
Timer keeps running after reaching zero — Store the interval ID and call clearInterval() when the countdown ends.
Seconds jump or skip — setInterval() is not perfectly precise. For long-running timers, calculate the remaining time fresh from new Date() on every tick rather than decrementing a counter variable. The implementation above already does this correctly.
Tips for Building Timers in JavaScript
Always clear the interval when the timer ends. A running interval that has no more work to do is a memory leak and a source of unnecessary computation.
Calculate from the current time on every tick. Do not decrement a variable by one each second — browser tabs can be throttled, intervals can drift, and the user might have their system clock change. Always subtract new Date() from the target for accuracy.
Pad your numbers. Two-digit display for all units looks professional. Single-digit numbers without padding look like bugs.
Handle the expired state explicitly. A timer that goes negative or freezes on zero is confusing. Show a message, hide the timer, or redirect — but handle it intentionally…..
A JavaScript countdown timer comes down to one calculation — subtracting the current time from a target time — repeated every second with setInterval(). The math to convert milliseconds into days, hours, minutes, and seconds is a handful of lines. The rest is presentation and edge case handling.
Build the simple version first. Then add the reusable class wrapper, the flip animation, and the time zone handling as your use case requires them. The foundation stays the same regardless of how much you layer on top..