JavaScript Date Object: Complete Guide

The JavaScript Date object represents a single moment in time. It stores dates as a timestamp (milliseconds since January 1, 1970 UTC) and provides methods to read and modify date components like year, month, day, hours, and minutes.

javascript

const now = new Date();
 
console.log(now.getFullYear());
console.log(now.getMonth());
console.log(now.getDate());

If today is July 14, 2026, this prints 2026, 6, and 14. The month is 6, not 7, because JavaScript months are zero-indexed: January is 0, December is 11.

For working with raw timestamps instead of date components, see the guide to working with timestamps.

Creating dates

There are four common ways to create a Date:

javascript

const now = new Date();
 
const specific = new Date(2026, 6, 14);
 
const fromString = new Date("2026-07-14");
 
const fromTimestamp = new Date(1721000000000);

The first creates the current moment. The second creates July 14, 2026 (month 6 is July). The third parses an ISO date string. The fourth creates a date from a millisecond timestamp.

When using the year-month-day constructor, the time defaults to midnight local time. You can also specify hours, minutes, seconds, and milliseconds:

javascript

const withTime = new Date(2026, 6, 14, 14, 30, 0);

Reading date components

The Date object provides get methods for each component. All return values in the local time zone unless prefixed with UTC.

javascript

const now = new Date();
 
console.log(now.getFullYear());
console.log(now.getMonth());
console.log(now.getDate());
console.log(now.getDay());
console.log(now.getHours());
console.log(now.getMinutes());

getFullYear returns the 4-digit year. Use this instead of the deprecated getYear which returns inconsistent values across date ranges.

The other get methods each return one component of the date, all in the local time zone:

Always add 1 to getMonth before displaying it to users, since months are zero-indexed but calendars are not.

For UTC values, use the UTC variants:

javascript

console.log(now.getUTCFullYear());
console.log(now.getUTCHours());

Modifying dates

Each get method has a corresponding set method that modifies the date in place. Instead of creating a new date, calling a set method changes the existing Date object and recalculates any related components automatically:

javascript

const meeting = new Date(2026, 6, 14);
 
meeting.setDate(meeting.getDate() + 7);
 
console.log(meeting.getDate());

This prints 21 because 7 days were added to the 14th. The Date object automatically handles month and year rollovers: adding 30 days to July 14 correctly produces August 13.

javascript

const date = new Date(2026, 6, 14);
 
date.setMonth(date.getMonth() + 2);
 
console.log(date.getMonth());

This prints 8 (September). The original July date becomes September 14. If the target month has fewer days, JavaScript adjusts automatically.

Comparing dates

Dates are compared by converting them to timestamps with getTime:

javascript

const deadline = new Date(2026, 11, 31);
const today = new Date();
 
if (today.getTime() < deadline.getTime()) {
  console.log("Still have time.");
}

getTime returns the millisecond timestamp, which is a plain number. Comparing two numbers tells you which moment is earlier. You can also subtract dates directly to get the difference in milliseconds:

javascript

const start = new Date(2026, 0, 1);
const end = new Date(2026, 6, 14);
 
const diffMs = end - start;
const diffDays = diffMs / (1000 * 60 * 60 * 24);
 
console.log(diffDays);

This prints the number of days between January 1 and July 14. Divide milliseconds by 1000 for seconds, by 60000 for minutes, by 3600000 for hours, and by 86400000 for days. The result is a plain JavaScript number, so the usual Number type rules for precision and rounding apply to it.

Common mistakes

Forgetting that months are zero-indexed is the most frequent Date bug. new Date(2026, 6, 14) is July 14, not June 14. Always subtract 1 from the human month number when constructing dates, and add 1 when displaying months to users.

Using getYear instead of getFullYear returns a two-digit year for some dates. getYear is deprecated and should never be used in new code.

Parsing date strings without the ISO format can produce inconsistent results across browsers. The string "07/14/2026" may be interpreted differently depending on the user's locale. Stick to "YYYY-MM-DD" ISO strings or the numeric constructor.

Calling Date() without new returns a string, not a Date object. Date() returns the current date as a string. new Date() returns a Date object. The difference is subtle and easy to miss.