JavaScript Date Object

Home » JavaScript Tutorial » JavaScript Built-in Objects & Methods » JavaScript Date Object

The Date object is JavaScript’s built-in tool for managing time. Whether building a countdown timer, a post timestamp, or a calendar, the Date object provides the methods necessary to track years, months, days, and milliseconds.

The Date Constructor vs. Date Function

A critical distinction exists between calling Date as a function and invoking it as a constructor with new.

  • Date() (Function call): Returns a string representing the current time. It does not create a Date object.
  • new Date() (Constructor call): Creates a new Date Object instance. This is required to access methods like .getFullYear() or .getMonth().
// Calling Date as a function returns a string
const dateString = Date();
console.log(typeof dateString); // Output: "string"

// Calling Date as a constructor returns an object
const dateObject = new Date();
console.log(typeof dateObject); // Output: "object"
JavaScript

Creating Dates

There are four primary ways to instantiate a new Date object.

  1. new Date(): Creates a date object for the current date and time (Right Now).
  2. Date String: Creates a date from a specific string format (e.g., "2025-12-25").
  3. Timestamp: Creates a date based on “Unix Time” (milliseconds since January 1, 1970).
  4. Components: Creates a date by specifying year, month, day, etc. as individual arguments.

Technical Note: Timezone Parsing

  • ISO Strings ("2025-01-01"): Parsed as UTC (Coordinated Universal Time).
  • Components (2025, 0, 1): Parsed as Local Time (based on the user’s system).
  • Result: This discrepancy can sometimes cause dates created via ISO strings to appear “off by one day” depending on the user’s timezone offset relative to UTC.
// 1. Current Time
const currenttime = new Date();
console.log(currenttime);
// Output: Weekday Month Day Year 00:00:00 GMT-0000 (Time Zone)

// 2. From a String (ISO Format - Defaults to UTC)
const isoDate = new Date("2025-12-25");
console.log(isoDate);
// Output: Wed Dec 24 2025 19:00:00 GMT-0500 (Eastern Standard Time)

// 3. From Components (Local Time)
// Note: MONTHS ARE 0-INDEXED (0 = January, 11 = December)
const specificDate = new Date(2025, 11, 25); 
console.log(specificDate);
// Output: Thu Dec 25 2025 00:00:00 GMT-0500 (Eastern Standard Time)

// 4. From Timestamp (Milliseconds since Epoch - January 1, 1970, UTC)
const fromEpoch = new Date(1766620800000);
console.log(fromEpoch);
// Output: Wed Dec 24 2025 19:00:00 GMT-0500 (Eastern Standard Time)
JavaScript

Date “Getter” Methods (Retrieving Data)

Once a date object is created, specific components (Year, Month, Day, etc.) can be extracted using “Getter” methods.

const now = new Date(); // Weekday Month Day Year 00:00:00 GMT-0000 (Time Zone)
console.log(now.getFullYear()); // Returns the 4-digit year. e.g., 2025
console.log(now.getMonth()); // Returns the month (0-11). 0 = Jan, 11 = Dec
console.log(now.getDate()); // Returns the day of the month. 1-31
console.log(now.getDay()); // Returns the day of the week. 0 = Sun, 6 = Sat
console.log(now.getHours()); // Returns the hour. 0-23
console.log(now.getMinutes()); // Returns the hour. 0-23
console.log(now.getSeconds()); // Returns the hour. 0-23
console.log(now.getTime()); // Returns milliseconds since 1970 or so. Total ms
// Milliseconds that have passed since the Unix epoch (midnight 1/1/1970 UTC [1]
JavaScript

Date “Setter” Methods & Autocorrection

Values within an existing Date object can be modified using “Set” methods.

Date Autocorrection: the Date object automatically handles overflow during modification. If a value exceeds its logical range, the Date object recalculates the date rather than throwing an error. This is useful for date arithmetic (e.g., adding 30 days).

  • setDate(32) in January – Rolls over to February 1st.
  • setDate(0) – Rolls back to the last day of the previous month.
const event = new Date(2025, 0, 1); // Jan 1, 2025 Local Time

// Standard Modification
event.setFullYear(2026); // Jan 1, 2026

// Autocorrection Example:
// Because 'event' is definitely in January, 
// setDate(0) correctly rolls back to Dec 31st of the previous year.
event.setDate(0); 

console.log(event.toDateString()); // Output: "Wed Dec 31 2025"
JavaScript

Date Formatting & Strings

By default, the standard string output of a date object is verbose. Modern JavaScript provides powerful localization options to format dates for users.

  • .toDateString(): Returns a simplified, readable date string (e.g., “Thu Dec 25 2025”).
  • .toISOString(): Returns the standard format for databases and APIs (UTC time).
  • .toLocaleDateString(locale, options): The preferred method for user-facing applications. It formats the date according to specific regional settings. Other options are toLocaleString() and toLocaleTimeString() to customize date formatting.
const myDate = new Date(); // Current Date/Time/Time Zone

// Basic Formatting
console.log(myDate.toDateString()); // Output: "Thu Dec 25 2025"
console.log(myDate.toISOString());  // Output: "2025-12-25T14:30:00.000Z"

// Advanced Locale Formatting
const options = { 
    weekday: 'long', 
    year: 'numeric', 
    month: 'long', 
    day: 'numeric' 
};

// Formats for US English
console.log(myDate.toLocaleDateString("en-US", options)); 
// Output: "Thursday, December 25, 2025"

console.log("----Extensive Options----");

// More extensive options including time and time zone
const extensiveOptions = {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
    hour: '2-digit',      // Example of adding hour
    minute: '2-digit',    // Example of adding minute
    second: '2-digit',    // Example of adding second
    hour12: false,        // Example of 24-hour format
    timeZone: 'UTC',      // Example of specifying a time zone
    timeZoneName: 'short' // Example of adding time zone name
};

// Using the extensive options
const extensivelyFormattedDate = myDate.toLocaleString('en-US', extensiveOptions);
console.log(extensivelyFormattedDate); 
// Output: Thursday, December 25, 2025, 01:45:15 UTC


console.log("----Simple Formatting----");

// Using dateStyle for a simpler format
// Options include: 'full', 'long', 'medium', 'short'
const simpleOptions = {
    dateStyle: 'medium', // Output: Dec 25, 2025
    timeStyle: 'short'   // Output: 1:45 PM
};

const simplyFormatted = myDate.toLocaleString('en-US', simpleOptions);
console.log(simplyFormatted);
// Output: Dec 25, 2025, 1:45 PM
JavaScript

Timestamps & Comparison

Internally, JavaScript stores dates as a single number: the timestamp. This allows for straightforward mathematical comparisons.

  • Date.now(): A static method that returns the current timestamp immediately, without needing to create a new Date() object.
  • Comparison: Operators like > and < work directly on Date objects by comparing their underlying timestamps.
console.log("----Days Difference Between 2 Dates----");

// Calculating difference between two dates
const date1_UTC = new Date("2025-01-01");
const date2_UTC = new Date("2025-12-25");
console.log(date1_UTC); // Tue Dec 31 2024 19:00:00 GMT-0500 (Eastern Standard Time)
console.log(date2_UTC); // Wed Dec 24 2025 19:00:00 GMT-0500 (Eastern Standard Time)

const date1_Local = new Date(2025, 0, 1);
const date2_Local = new Date(2025, 11, 25);
console.log(date1_Local); // Wed Jan 01 2025 00:00:00 GMT-0500 (Eastern Standard Time)
console.log(date2_Local); // Thu Dec 25 2025 00:00:00 GMT-0500 (Eastern Standard Time)

if (date2_Local > date1_Local) {
    console.log("Date 2 is later in the year.");
} // Output: Date 2 is later in the year.

// Math: Subtracting dates returns the difference in milliseconds
const differenceInMs = date2_Local - date1_Local;
console.log(differenceInMs); // Output: 30931200000

// Convert Ms to Days: MS / (24h / 60m / 60s / 1000ms)
// 30931200000 / (24 * 60 * 60 * 1000) = 358
const days = differenceInMs / (24 * 60 * 60 * 1000);
console.log(`Difference: ${days} days`);
// Output: Difference: 358 days

console.log("----Current Time Years Difference----");

// Get current timestamp directly
const currentDateTime = new Date();
console.log(currentDateTime); // Output: Current Date/Time

const newYear00 = new Date(2000, 0, 1);
console.log(newYear00); // Sat Jan 01 2000 00:00:00 GMT-0500 (Eastern Standard Time)

const diffYearsMS = currentDateTime - newYear00;
console.log(diffYearsMS); // Millisecond Difference

const diffYears = diffYearsMS / (365.25 * 24 * 60 * 60 * 1000) // 365.25 accounts for leap years.
console.log(diffYears); // Output: ##.##... (Years with decimals)

const diffYearsFormatted = Math.trunc(diffYears);
console.log(diffYearsFormatted); // Output: ## (Year difference as integer)
JavaScript

Common Pitfall: “Month 0”

The most frequent error in Date handling is forgetting that Months are zero-indexed in the component constructor, but Days are one-indexed.

  • new Date(2025, 0, 1) is January 1st.
  • new Date(2025, 1, 1) is February 1st.

However, when using a String, numbers represent the month conventionally:

  • new Date("2025-01-01") is January 1st.

External Libraries & Ecosystem

While the native Date object is capable, it contains historical design choices—such as mutability and zero-indexed months—that can lead to bugs in complex applications. Consequently, the JavaScript ecosystem relies heavily on third-party libraries to simplify date manipulation, formatting, and timezone management.

Historically, Moment.js was the standard, but it is now considered “legacy” due to its large file size and mutable design. Modern development favors the following alternatives:

  • date-fns: A modular, function-based library. It allows developers to import only the specific functions needed (e.g., addDays, format), keeping the application file size small (“tree-shaking”). It works with standard native Date objects.
  • Day.js: A minimalist library (approx. 2kB) with an API largely compatible with Moment.js. It is immutable, meaning operations like adding days return a new instance rather than modifying the original.
  • Luxon: Created by the maintainers of Moment.js. It provides a robust, immutable DateTime class with native time zone support (via the Intl API) and duration handling.

While this overview covers the most common Date prototypes, you can refer to the Date object prototypes in your console with console.dir(Date.prototype) for a complete list of every built-in prototype available for further experimentation.

< Previous
Next Lesson >