Welcome to our ultimate guide on the JavaScript Date object and Moment.js. This tutorial will teach you everything you need to know about working with dates and times in your projects.

How to Create a Date Object

Get the current date and time

const now = new Date();

// Mon Aug 10 2019 12:58:21 GMT-0400 (Eastern Daylight Time)

Get a date and time with individual values

const specifiedDate = new Date(2019, 4, 29, 15, 0, 0, 0);

// Wed May 29 2019 15:00:00 GMT-0400 (Eastern Daylight Time)

The syntax is Date(year, month, day, hour, minute, second, millisecond). Note that the months are zero indexed, beginning with January at 0 and December at 12.

Get a date and time from a timestamp

const unixEpoch = new Date(0);

This represents the time at Thursday, January 1st, 1970 (UTC), or the UNIX Epoch time. The UNIX Epoch is important because it's what JavaScript, Python, PHP, and other languages and systems use internally to calculate the current time.

new Date(ms) returns the date of the epoch plus the number of milliseconds you pass in. In a day there's 86,400,000 milliseconds so:

const dayAfterEpoch = new Date(86400000);

will return Friday, January 2nd, 1970 (UTC).

An important thing to remember is that UNIX timestamps are based on seconds, and JavaScript Date objects are based on milliseconds since the epoch. If you need to convert a UNIX timestamp to a JavaScript date, simply do the following:

const unixTimestamp = 1555804800;
const date = new Date(unixTimestamp * 1000);

// Sun Apr 21 2019 09:00:00 GMT-0400 (Eastern Daylight Time)

Get a date and time from a string

const stringDate = new Date('May 29, 2019 15:00:00');

// Wed May 29 2019 15:00:00 GMT-0400 (Eastern Daylight Time)

Getting the date this way is very flexible. All of the examples below return valid Date objects:

new Date('2019-06') // June 1st, 2019 00:00:00
new Date('2019-06-16') // June 16th, 2019
new Date('2019') // January 1st, 2019 00:00:00
new Date('JUNE 16, 2019')
new Date('6/23/2019')

Just be careful about the positioning of the month and day to prevent so the month isn't interpreted as the day.

You can also use the Date.parse() method to return a timestamp rather than a Date object:

You can also use the Date.parse() method to return the number of milliseconds since the epoch (January 1st, 1970):

Date.parse('1970-01-02') // 86400000
Date.parse('6/16/2019') // 1560610800000

Setting a time zone

When passing a date string without setting a time zone, JavaScript assumes the date/time are in UTC before converting it to your browser's time zone:

const exactBirthdate = new Date('6/13/2018 06:27:00');

console.log(exactBirthdate) // Wed Jun 13 2018 06:27:00 GMT+0900 (Korean Standard Time)

This can lead to errors where the date returned is off by many hours. To avoid this, pass in a time zone along with the string:

const exactBirthdate = new Date('6/13/2018 06:27:00 GMT-1000');

console.log(exactBirthdate) // Thu Jun 14 2018 01:27:00 GMT+0900 (Korean Standard Time)

/*
These formats also work:

new Date('6/13/2018 06:27:00 GMT-10:00');
new Date('6/13/2018 06:27:00 -1000');
new Date('6/13/2018 06:27:00 -10:00');
*/

You can also pass some, but not all, time zone codes:

const exactBirthdate = new Date('6/13/2018 06:27:00 PDT');

console.log(exactBirthdate) // Thu Jun 14 2018 01:27:00 GMT+0900 (Korean Standard Time)

If you pass in an invalid time zone code, JavaScript will fall back to UTC time before converting to your local time. Also, if there's something wrong with the number format of the date or time, you'll get an Invalid Date error.

Date Object Methods

Often you will not need the entire date, but just part of it like the day, week or month. Fortunately there are a number of methods to do just that:

const date = new Date('6/13/2018 06:27:39');

date.getMonth() // 5 (0 is January)
date.getDate() // 13
date.getDay() // 3 (0 is Sunday)
date.getFullYear() // 2018
date.getTime() // 1528838859000
date.getHours() // 6
date.getMinutes() // 27
date.getSeconds() // 39
date.getTimezoneOffset() // -540 (time zone offset in minutes based on your browser's location)

Make Working with Dates Easier with Moment.js

Getting dates and times right is no small task. Every country seems to have a different way of formatting dates, and accounting for different time zones and daylight savings/summer time takes, well, a whole lot of time. That's where Moment.js shines – it makes parsing, formatting, and displaying dates a breeze.

To start using Moment.js, install it through a package manager like npm, or add it to your site through a CDN. See the Moment.js documentation for more details.

Get the current date and time with Moment.js

const now = moment();

This returns an object with the date and time based on your browser's location, along with other locale information. It's similar to native JavaScript's new Date().

Get a date and time from a timestamp with Moment.js

Similar to new Date(ms), you can pass the number of milliseconds since the epoch to moment():

const dayAfterEpoch = moment(86400000);

If you want to get a date using a UNIX timestamp in seconds, you can use the unix() method:

const dayAfterEpoch = moment.unix(86400);

Get a date and time from a string with Moment.js

Parsing a date from a string with Moment.js is easy, and the library accepts strings in the ISO 8601 or RFC 2822 Date Time format, along with any string accepted by the JavaScript Date object.

ISO 8601 strings are recommended since they are quite flexible. Here are some examples using that format:

moment('2019-04-21');
moment('2019-04-21T05:30');
moment('2019-04-21 05:30');

moment('20190421');
moment('20190421T0530');

Setting a time zone with Moment.js

Up until now, we have been using Moment.js in local mode, meaning that any input is assumed to be a local date or time. This is similar to how the native JavaScript Date object works:

const exactBirthMoment = moment('2018-06-13 06:27:00');

console.log(exactBirthMoment) // Wed Jun 13 2018 06:27:00 GMT+0900 (Korean Standard Time)

However, to set a time zone, you must first get the Moment object in UTC mode:

const exactBirthMoment = moment.utc('2018-06-13 06:27:00');

console.log(exactBirthMoment) // Wed Jun 13 2018 15:27:00 GMT+0900 (Korean Standard Time)

Then you can adjust for the difference in time zones with the utcOffset() method:

const exactBirthMoment = moment.utc('2018-06-13 06:27:00').utcOffset('+10:00');

console.log(exactBirthMoment) // Wed Jun 13 2018 06:27:00 GMT+0900 (Korean Standard Time)

You can set the UTC offset as a number or a string:

moment.utc().utcOffset(10) // Number of hours offset
moment.utc().utcOffset(600) // Number of minutes offset
moment.utc().utcOffset('+10:00') // Number of hours offset as a string

To use named time zones (America/Los_Angeles) or time zone codes (PDT) with Moment objects, check out the Moment Timezone library.

Format the date and time with Moment.js

One of the major strengths that Moment.js has over native JavaScript Date objects is how easy it is to format the output date and time. Just chain the  format() method to a Moment date object and pass it a format string as a parameter:

moment().format('MM-DD-YY'); // "08-13-19"
moment().format('MM-DD-YYYY'); // "08-13-2019"
moment().format('MM/DD/YYYY'); // "08/13/2019"
moment().format('MMM Do, YYYY') // "Aug 13th, 2019"
moment().format('ddd MMMM Do, YYYY HH:mm:ss') // "Tues August 13th, 2019 19:29:20"
moment().format('dddd, MMMM Do, YYYY -- hh:mm:ss A') // "Tuesday, August 13th, 2019 -- 07:31:02 PM"

Here's a table with some common formatting tokens:

Input Output Description
YYYY 2019 4 digit year
YY 19 2 digit year
MMMM August Full month name
MMM Aug Abbreviated month name
MM 08 2 digit month
M 8 1 digit month
DDD 225 Day of the year
DD 13 Day of the month
Do 13th Day of the month with ordinal
dddd Wednesday Full day name
ddd Wed Abbreviated day name
HH 17 Hours in 24 hour time
hh 05 Hours in 12 hour time
mm 32 Minutes
ss 19 Seconds
a am / pm Ante or post meridiem
A AM / PM Capitalized ante or post meridiem
ZZ +0900 Timezone offset from UTC
X 1410715640.579 Unix timestamp in seconds
XX 1410715640579 Unix timestamp in milliseconds

Working with JavaScript Date objects and Moment.js doesn't have to be time consuming. Now you should know more than enough to get started with both.