JavaScript: Dates and Time

Introduction to JavaScript Date Object

Understanding and manipulating dates and times is crucial for creating dynamic web applications. JavaScript offers a built-in Date object for handling these tasks. This guide covers how to create dates, read and change their parts, format them, and do date arithmetic — with runnable examples throughout.

Internally, a Date is just a single number: the count of milliseconds since the Unix epoch (00:00:00 UTC on January 1, 1970). Every other feature is built on top of that one number, so a lot of date logic boils down to ordinary number math.

Creating Date Objects

There are four common ways to instantiate a Date, each for a different input.

// 1. Current date and time (no arguments)
const now = new Date();

// 2. From a millisecond timestamp (epoch = 0)
const epoch = new Date(0); // 1970-01-01T00:00:00.000Z

// 3. From a date string (ISO 8601 is the only reliably portable format)
const parsed = new Date("2024-01-01T00:00:00");

// 4. From individual components: year, monthIndex, day, hours, minutes, seconds
const detailed = new Date(2024, 0, 1, 15, 30, 0); // Jan 1, 2024, 15:30:00

Parsing ISO strings vs. other formats

Only the ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ) is guaranteed to parse the same way in every engine. A bare date string like "2024-01-01" is treated as UTC midnight, while "2024-01-01T00:00:00" (no Z) is treated as local time. Other formats (e.g. "01/02/2024") are implementation-dependent — avoid them.

Retrieving Date and Time Components

Once you have a Date, you can read each part with a get* method. These return local-time values (see Working with Time Zones for the UTC variants).

Setting Date and Time Components

Each get* method has a matching set* method that mutates the date in place. Date objects are mutable — set* changes the original rather than returning a new date.

Autocorrection (overflow rolls over)

If you set a value out of range, Date quietly normalizes it — there is no error. Setting day 32 of January rolls forward into February. This is genuinely useful for arithmetic: to add 5 days, just add 5 to getDate() and let the date roll over.

Timestamps: getTime and Date.now

getTime() returns the date as a millisecond timestamp, and the static Date.now() returns the current timestamp without creating an object. Timestamps are the easiest way to compare dates or measure elapsed time.

Working with Time Zones

A Date stores a single UTC instant; the get* methods read it in the host's local time zone. Use the getUTC* variants to read the UTC value, and the Intl API (via toLocaleString) to render any other zone.

Formatting Dates and Times

To produce a machine-readable string use toISOString(); for human-readable output, toLocaleDateString() / toLocaleTimeString() respect the user's locale. For a fully custom layout, assemble the parts yourself (remembering getMonth() + 1).

Date Arithmetic and Differences

Because a Date is a number under the hood, subtracting one date from another gives the difference in milliseconds. The subtraction operator coerces each date via getTime(), so endDate - startDate works directly. Divide by the milliseconds in a day to get a day count.

To add time, prefer mutating with set* (which handles month/year overflow correctly) over adding raw milliseconds, which ignores daylight-saving shifts.

Leveraging Libraries for Advanced Manipulations

For more complex date manipulations and formatting, several libraries can simplify these tasks. Libraries such as date-fns and Luxon offer extended functionalities beyond the native Date object, facilitating tasks like parsing, internationalization, and complex time zone handling. Additionally, the Temporal API is currently in development to eventually replace the native Date object with a more robust, immutable, and timezone-aware solution.

Conclusion

Mastering the Date object in JavaScript is essential for developing dynamic web applications that interact with dates and times effectively. Through creating, retrieving, setting, and formatting dates, developers can build sophisticated features that respond to real-world time. Whether it's scheduling events, calculating durations, or displaying timelines, the capabilities provided by JavaScript's Date object and various third-party libraries make date and time manipulation a powerful tool in your web development arsenal.

Practice