JavaScript: Date Tutorial

By Xah Lee. Date: . Last updated: .

First, here's a quick usage example:

// create a date instance of current date time
var dd = new Date();

var hh = dd.getHours();
var mm = dd.getMinutes();
var ss = dd.getSeconds();

console.log(
    hh + ":" + mm + ":" + ss
); // sample output: 16:49:44

console.log ( dd.getFullYear() ); // 2016

console.log ( dd.getDate() ); // 23
// first day of month is 1.

console.log ( dd.getMonth() ); // 11
// warning: January is 0, December is 12

console.log ( dd.getDay() ); // 5
// Sunday is 0. Saturday is 6.

Creating Date Object

new Date()

new Date() → Returns a date object that represents the datetime when this code is evaluated.

new Date(1428605303481)

new Date(milliseconds) → Returns a date object that represents the datetime of milliseconds since 01 January, 1970 UTC.

This milliseconds is how JavaScript represents datetime internally.

This is the same value returned by datetime.getTime() method.

new Date("2015-04-08T15:48:22.000Z")

new Date(datestring) → Returns a date object that represents the datetime in datestring.

console.log(
    (new Date("2016-04-08T15:48:22.000Z")).toUTCString()
);
// Fri, 08 Apr 2016 15:48:22 GMT

The format of datestring is of this form “yyyy-mm-ddThh:mm:ss.sssZ”. The “sss” is milliseconds. The “Z” stands for UTC. Example: "2016-04-08T15:48:22.000Z".

It is the same format returned by (new Date()).toISOString()

Trailing parts of the string can be omitted, but you should not, because browsers behavior are different.

new Date(2016, 0, 1, …)

new Date(year, month, day, hours, minutes, seconds, ms) → Returns a date object of given (local) datetime.

The arguments are interpreted as local time. (If you want args to be UTC, use static method Date.UTC(…).) 〔➤see JavaScript: Date.prototype

  1. The year, month are required, other parameters are optional.
  2. year → 4 digits integer.
  3. month → 0 to 11. January is 0.
  4. day → 1 to 31.
  5. hours → 0 to 23.
  6. minutes → 0 to 59.
  7. seconds → 0 to 59.
  8. ms → 0 to 999.
// WARNING: January is 0
console.log(
    (new Date(2016,0,1)).toUTCString()
);
// Fri, 01 Jan 2016 08:00:00 GMT

For detail, see JavaScript: Date() Constructor

Static Methods

Date() → Returns a string that represents the datetime this code is evaluated. Any arguments are ignored. This is equivalent to (new Date()).toString(). Sample return value: "Wed Apr 08 2015 08:36:13 GMT-0700 (PDT)".

console.log(
    Date()
);
// Tue Apr 26 2016 16:53:05 GMT-0700 (PDT)

Date.now() → returns the millisecond representation of date when this code is called. Same as (new Date()).getTime(). Sample return value: 1428601360919.

Date.parse(date_time_string) → Parses date_time_string, returns the millisecond representation of that date.

Date.UTC(…) → Returns a date object. The arguments are the same as new Date(), but interprets them as UTC.

〔➤see JavaScript: Date.prototype

Date Object Get Methods

Most date get methods have 2 versions. One returns local time info, one returns UTC time info. For example, getHours() vs getUTCHours().

// example of using Date get methods
var dt = new Date("2017-06-13T21:00:01.000Z");

console.log( dt.getFullYear() ); // 2017
console.log( dt.getUTCMonth() ); // 5
console.log( dt.getUTCDate() ); // 13
console.log( dt.getUTCDay() ); // 2 (Tuesday)
console.log( dt.getUTCHours() ); // 21
console.log( dt.getUTCMinutes() ); // 0
console.log( dt.getUTCSeconds() ); // 1

console.log( dt.getFullYear() ); // 2017
console.log( dt.getMonth() ); // 5
console.log( dt.getDate() ); // 13
console.log( dt.getDay() ); // 2 (Tuesday)
console.log( dt.getHours() ); // 14
console.log( dt.getMinutes() ); // 0
console.log( dt.getSeconds() ); // 1

Date Object Set Methods

You can also set a date object's year, month, or any of the parts. Here's a example of setting the minutes part.

var d = new Date("2017-04-08T06:00:10.000Z");
console.log ( d ); // 2017-04-08T06:00:10.000Z
d.setMinutes(30);
console.log ( d ); // 2017-04-08T06:30:10.000Z

For full list of set methods, see JavaScript: Date.prototype

What is the difference between UTC and GMT?

For practical purposes, they are the same.

UTC (Coordinated Universal Time) is a time standard based on atomic clock.

GMT (Greenwich Mean Time) is a older time standard.

“Zulu time” is a term used in military and is the same as GMT. (GMT and UTC has a abbrev of Z, because Z is like zero. Z in NATO phonetic alphabet is read as Zulu. That's why GMT/UTC is also Zulu time. )

Compute Date Range

JavaScript: Compute Date Range

For complete reference, see:

Like what you read? Buy JavaScript in Depth
or, buy a new keyboard, see Keyboard Reviews.