Table of Contents

URL: https://www.progressiverobot.com/js-date-object/

There are some great libraries out there to deal with dates in JavaScript, with Moment.js and date-fns being perhaps the two most popular. It's very common however to have just some basic needs for playing with dates and using a library instead of the native JavaScript date object would be overkill. Let's therefore explore what we can do natively using the date object.

Creating Date Objects

date object illustration for: Creating Date Objects

Creating a new date instance is as easy as newing up a date object.

Without arguments, we get the current date and time in the local timezone:

				
					
const now = new Date();



console.log(now); // Wed Dec 06 2017 18:30:55 GMT-0800 (PST)

Milliseconds Since Unix Epoch

You can also pass-in an integer for a date object that's X amount of milliseconds after January 1st 1970 UTC:

				
					
const latter = new Date(4000000000);



console.log(latter); // Sun Feb 15 1970 23:06:40 GMT-0800 (PST)

Date String

You can also alternatively create a date object by passing a string:

				
					
const summerOf95 = new Date("1995-06-28");



// or, with a full date string that also includes the time and the time zone. Note here that `Z` is for UTC timezone:

const december31st = new Date("1999-12-31T02:56:03.392Z");

Date Components

Finally, you can create a date object in your local timezone using separate component argument:

				
					
const someDate = new Date(2000, 5, 20, 16, 34, 12, 24);



console.log(someDate); // Tue Jun 20 2000 16:34:12 GMT-0700 (PDT)

Notice how the months are zero-based, and 5 therefore represents June. Components for time can be omitted and 0 will be assumed:

				
					
const someDate = new Date(2000, 5, 20, 16, null, 12, 24);



console.log(someDate); // Tue Jun 20 2000 16:00:12 GMT-0700 (PDT)

[warning] If you're confused by the date returned when console logging a date object, remember that most browsers output the time in your local timezone.

Timestamps

Get a timestamp (number of milliseconds since Jan 1st 1970 UTC) using a date instance's <^>getTime<^> method:

				
					
const nowTimestamp = new Date().getTime();



console.log(nowTimestamp); // 1512616153783

Timestamp for now

In the above example, we're getting the timestamp for now. This is so common that JavaScript now has a method to get just that more easily:

				
					
const nowTimestamp = Date.now();



console.log(nowTimestamp); // 1512616153783

—

Timestamps are useful to easily calculate the difference in milliseconds between two dates. For example, here we get the difference in milliseconds between Feb 3rd 1996 and Jan 1 1970:

				
					
const diff = new Date("1995-02-03").getTime() - new Date(0).getTime();

In the above case, you can ommit the call to <^>getTime<^> and the dates will automatically be coerced to timestamps:

				
					
const diff = new Date("1995-02-03") - new Date(0);

Human Readable Strings

Date object instances also give us a few useful methods to get human-friendly string representations. The <^>toDateString<^>, <^>toTimeString<^>, <^>toLocaleDateString<^>, <^>toLocaleString<^>, <^>toLocaleTimeString<^> and <^>toUTCString<^> methods are the most useful ones, and demonstrated in the following example:

				
					
const now = new Date();



console.log(now.toDateString()); // Wed Dec 06 2017

console.log(now.toTimeString()); // 19:23:42 GMT-0800 (PST)

console.log(now.toLocaleDateString()); // 12/6/2017

console.log(now.toLocaleString()); // 12/6/2017, 7:20:28 PM

console.log(now.toLocaleTimeString()); // 7:20:51 PM

console.log(now.toUTCString()); // Thu, 07 Dec 2017 03:21:14 GMT

Getting Date or Time Components

You can get specific date/time components from a date instance using the following methods:

  • <^>getFullYear()<^>: The year, using 4 digits.
  • <^>getDate()<^>: The day of the month (e.g: 31).
  • <^>getMonth()<^>: A zero-based integer for the month (e.g: 0 for January).
  • <^>getDay()<^>: The index for the day of the week from 0 for Sunday up to 6 for Saturday.
  • <^>getHours()<^>: The hour of the day.
  • <^>getMinutes()<^>: The minutes.
  • <^>getSeconds()<^>: The seconds.
  • <^>getMilliseconds()<^>: The milliseconds.

Here's a simple example:

				
					
const now = new Date();



console.log(`It's ${now.getHours()}:${now.getMinutes()} o'clock`);

// It's 19:34 O'Clock

Note that all the above methods return date/time components in the local timezone. Each method has an equivalent so that UTC date/time is returned instead (e.g: <^>getUTCMinutes()<^>).

Setting Date or Time Components

Similar to how we can get date/time components, we can also set them using analogous methods:

				
					
const now = new Date();



now.setFullYear(2049);



console.log(now.toLocaleString()); // 12/6/2049, 7:40:04 PM

Note that there's a shortcut where most of the set methods can take multiple arguments to set the other components. These two snippets produce the same result:

				
					
[label The tedious way]

const now = new Date();





				
			
				
					
[label The shortcut]

const now = new Date();

Adding/Subtracting Time

Using a combination of the get and set methods, you can add to or subtract from the date/time components of a date instance. Here for example, we add 15 minutes to the current time:

				
					
const now = new Date();



console.log(now.toLocaleTimeString()); // 7:47:53 PM



now.setMinutes(now.getMinutes() + 15);



console.log(now.toLocaleTimeString()); // 8:02:53 PM