Date And Time

Working with dates is unavoidable in real applications — event schedulers, countdowns, activity logs, and timestamps all depend on it. JavaScript's built-in Date object handles this, though it has some quirks worth understanding. Once you know its patterns, you can confidently build anything from a simple clock to a booking system.

Creating Dates

The Date constructor gives you several ways to create a date object.

// Current date and time
const now = new Date();
console.log(now); // e.g. 2026-03-02T14:30:00.000Z

// From a date string
const release = new Date("2024-01-15");
console.log(release.toDateString()); // Mon Jan 15 2024

// From individual components: year, month (0-indexed!), day, hour, minute, second
const meeting = new Date(2026, 2, 15, 9, 30, 0); // March 15, 2026 at 09:30
console.log(meeting.toLocaleString()); // 3/15/2026, 9:30:00 AM

// From a Unix timestamp (milliseconds since Jan 1, 1970)
const epoch = new Date(0);
console.log(epoch.toUTCString()); // Thu, 01 Jan 1970 00:00:00 GMT

// Get the current timestamp as a number
console.log(Date.now()); // e.g. 1740924600000

The most common gotcha: months are zero-indexed. January is 0, December is 11. This trips up even experienced developers.

Reading Date Components

Once you have a Date object, you can extract its individual parts using getter methods.

const event = new Date(2026, 5, 20, 14, 45, 30); // June 20, 2026 at 14:45:30

console.log(event.getFullYear());  // 2026
console.log(event.getMonth());     // 5 (June — zero-indexed)
console.log(event.getDate());      // 20 (day of the month)
console.log(event.getDay());       // 6 (Saturday — 0 is Sunday)
console.log(event.getHours());     // 14
console.log(event.getMinutes());   // 45
console.log(event.getSeconds());   // 30
console.log(event.getTime());      // milliseconds since epoch

// Useful: build a human-readable label
const days = ["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"];
const months = ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"];

const label = `${days[event.getDay()]}, ${months[event.getMonth()]} ${event.getDate()}, ${event.getFullYear()}`;
console.log(label); // Saturday, Jun 20, 2026

Formatting Dates

JavaScript provides built-in formatting through toLocaleDateString, toLocaleTimeString, and the powerful Intl.DateTimeFormat API.

const date = new Date(2026, 2, 2, 9, 5, 0); // March 2, 2026 at 09:05

// Simple locale-aware formatting
console.log(date.toLocaleDateString("en-US")); // 3/2/2026
console.log(date.toLocaleDateString("en-GB")); // 02/03/2026
console.log(date.toLocaleTimeString("en-US")); // 9:05:00 AM

// Full control with Intl.DateTimeFormat
const formatter = new Intl.DateTimeFormat("en-US", {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
});
console.log(formatter.format(date)); // Monday, March 2, 2026

// Compact time display
const timeFormatter = new Intl.DateTimeFormat("en-US", {
  hour: "2-digit",
  minute: "2-digit",
  hour12: true,
});
console.log(timeFormatter.format(date)); // 09:05 AM

// ISO string — useful for APIs and storage
console.log(date.toISOString()); // 2026-03-02T09:05:00.000Z

Intl.DateTimeFormat is the modern, locale-aware approach. Prefer it over manual string building.

Comparing and Calculating Dates

Because Date objects expose their underlying timestamp via .getTime(), you can compare and calculate differences using arithmetic.

const start = new Date(2026, 0, 1);   // Jan 1, 2026
const end   = new Date(2026, 11, 31); // Dec 31, 2026

// Direct comparison using timestamps
console.log(start < end);   // true
console.log(start.getTime() === end.getTime()); // false

// Calculate the difference in days
const MS_PER_DAY = 1000 * 60 * 60 * 24;
const diffMs   = end.getTime() - start.getTime();
const diffDays = Math.round(diffMs / MS_PER_DAY);
console.log(`Days between: ${diffDays}`); // Days between: 364

// Days until a future date
function daysUntil(targetDate) {
  const today = new Date();
  today.setHours(0, 0, 0, 0); // normalize to midnight
  const diff = targetDate.getTime() - today.getTime();
  return Math.ceil(diff / MS_PER_DAY);
}

const nextYear = new Date(2027, 0, 1);
console.log(`Days until 2027: ${daysUntil(nextYear)}`);

Normalizing time to midnight with setHours(0, 0, 0, 0) is important when you only care about calendar dates, not specific times.

Modifying Dates

Every getter has a matching setter, letting you adjust parts of a date in place.

const deadline = new Date(2026, 2, 2); // March 2, 2026

// Add 30 days
deadline.setDate(deadline.getDate() + 30);
console.log(deadline.toDateString()); // Sat Apr 01 2026

// Add 3 months
const nextQuarter = new Date(2026, 2, 2);
nextQuarter.setMonth(nextQuarter.getMonth() + 3);
console.log(nextQuarter.toDateString()); // Wed Jun 03 2026 (handles overflow)

// Build an "expires at" timestamp 1 hour from now
const expiresAt = new Date();
expiresAt.setHours(expiresAt.getHours() + 1);
console.log(`Session expires: ${expiresAt.toLocaleTimeString()}`);

JavaScript automatically handles overflow — adding 31 days to January 31st correctly rolls over to March 3rd (or 4th in a leap year).

Try It Yourself

Build a countdown timer function that returns a human-readable summary of the time remaining until a target date.

function countdown(targetDate) {
  const now = Date.now();
  const target = new Date(targetDate).getTime();
  const diff = target - now;

  if (diff <= 0) return "This event has already passed.";

  const MS = { day: 86400000, hour: 3600000, minute: 60000, second: 1000 };

  const days    = Math.floor(diff / MS.day);
  const hours   = Math.floor((diff % MS.day) / MS.hour);
  const minutes = Math.floor((diff % MS.hour) / MS.minute);
  const seconds = Math.floor((diff % MS.minute) / MS.second);

  const parts = [];
  if (days)    parts.push(`${days}d`);
  if (hours)   parts.push(`${hours}h`);
  if (minutes) parts.push(`${minutes}m`);
  if (seconds) parts.push(`${seconds}s`);

  return `Time remaining: ${parts.join(" ")}`;
}

// Try changing this to a future date
console.log(countdown("2026-12-31T00:00:00"));
console.log(countdown("2025-01-01")); // already passed
console.log(countdown("2027-06-15T09:00:00"));

Challenges:

Add a label parameter and include it in the output (e.g., "New Year: 10d 5h 20m 3s")
Format the date target itself using Intl.DateTimeFormat and include it in the output
Make the function return an object { days, hours, minutes, seconds } instead of a string

Key Takeaways

new Date() returns the current date and time; Date.now() returns the raw millisecond timestamp
Months are zero-indexed — January is 0, December is 11
Use getTime() to convert a date to a number for arithmetic and comparisons
Use Intl.DateTimeFormat for locale-aware, user-friendly date formatting
Normalize dates to midnight with setHours(0, 0, 0, 0) when comparing calendar days
toISOString() produces a consistent, timezone-neutral string suitable for APIs and storage
JavaScript handles date overflow automatically — adding too many days or months rolls into the next period correctly

Pro Tip: For production applications that handle timezones, recurring events, or complex date math, reach for a library like date-fns or Temporal (the modern TC39 proposal replacing Date). The built-in Date object uses local timezone by default and can behave unexpectedly across regions — always use toISOString() or UTC methods when storing or transmitting dates between systems.