// Tutorial //

Exploring the JavaScript Date Object

Published on December 6, 2017
Default avatar
By Alligator.io
Developer and author at DigitalOcean.
Exploring the JavaScript 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

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)

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:

The tedious way
const now = new Date();


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

Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up
About the authors
Default avatar
Developer and author at DigitalOcean.

Still looking for an answer?

Was this helpful?