# JavaScript Date Object

The JavaScript Date object can be used to work with dates and time within a JavaScript program. A Date object contains a number that represents the milliseconds since the Unix Epoch or January 1, 1970.

# Create a New Date Object

A new date object can be created by using the Date() constructor. Like with all constructors, the new keyword must also be used.

const d = new Date()

The Date() constructor can take different parameters, which are used to determine the single moment in time that Date object will hold.

# No Parameter

If no parameter is given, the Date object will be set to the current date and time.

const d = new Date()

# A Timestamp

An integer representing the number of milliseconds since January 1, 1970 00:00:00 UTC can be given.

const d = new Date(1500000000000)

# A Date String

A string value representing a date and in a format recognized by the Date.parse() method can be given. The standard date-time string format is as follows:

const d = new Date('July 13, 2017 22:40')

# Individual Date Components

Each part of a date (year, month, day, hour, minute, second, and millisecond) can be given as a separate parameter. Only the year and month are required and any missing fields will be given the lowest possible value.

When working with Date components, it is important to remember that the month values begins with 0 for January and ends with 11 for December.

const d = new Date(2017, 6, 13, 22, 40)

# Instance Methods

Date instance methods can be used to get, set, or display dates. The following methods are some of the more commonly used.

# Getting Date Elements

It is possible to get any part of a Date instance using methods.

# Setting Date Elements

It is possible to set any part of the Date instance using methods. The following methods are some of the more commonly used.

# Displaying Dates

Date methods can be used to display dates in different formats. The following methods are some of the more commonly used.

# Calculating Difference

Calculating the difference between dates, either time passed or a count down to, is a common use of the dates in JavaScript. The following are examples of how to do those calculations.

# Comparing Dates

Because all dates in JavaScript are essentially based on the number of milliseconds since the Unix Epoch, it can be one of the easiest ways to compare dates. The getTime() method can be used to get the number of milliseconds for a specific Date instance.

const canadaDay = new Date('July 1, 2020')
const newYear = new Date('January 1, 2021')

canadaDay.getTime() // 1593576000000
newYear.getTime()   // 1609477200000

As we can see from the example above the later a date is, the larger the number returned from the getTime() method. Because getTime() returns a number, standard compares can be used.

const canadaDay = new Date('July 1, 2020')
const now = new Date()

if (now.getTime() < canadaDay.getTime()) {
  document.write("Still waiting for Canada Day.")
} else {
  document.write("Canada Day has passed.")
}

Of course, sometimes we are looking for a specific date, and we need to know two dates match. This can be accomplished by comparing the different components of the two Date instances.

const canadaDay = new Date('July 1, 2020')
const independenceDay = new Date('July 4, 2020')

canadaDay.getMonth() === independenceDay.getMonth() // true
canadaDay.getDate() === independenceDay.getDate() // false

# Countdown

Creating a countdown or an elapsed time, simply involves subtracting one date by another using the getTime(). You may wish to convert the milliseconds to a larger unit like hours or days.

const canadaDay = new Date('July 1, 2020')
const now = new Date()

// convert milliseconds to days
// since we want whole days Math.floor is used to drop extra time
function msToDays (date) {
  return Math.floor(date.getTime() / 1000 / 60 / 60 / 24)
}

// Calculating difference
const difference = msToDays(canadaDay) - msToDays(now)

if (difference > 0) {
  // Canada Day has yet to come
} else if (difference < 0) {
  // Canada Day has passed
} else {
  // It is Canada Day
}

# See Also

• Timestamps, Date.now() and valueOf() | YouTube
• International Date & Time Formatting with JavaScript | YouTube
• A Complete Tutorial on the new MomentJS Library - Luxon JS | YouTube

# References

• Date object