Fred Brack   Fred Brack  
Raleigh, NC
Picture of the Cape Hatteras lighthouse

An Introduction to JavaScript Dates
by Fred Brack

This is not a full tutorial on JavaScript dates but rather an introduction and reference to their basic features and how to manipulate them.  Want more detail?  Try Learn-JS, which helped me; and my favorite reference site is W3Schools.  I created this web page to help me document my understanding of JavaScript dates as I progressed from novice to intermediate user ... and because I like to document stuff for others!  I hope you find it useful.

What Is the JavaScript Date Object?

JavaScript provides a special object called the Date objectDate() – which represent a single moment in time in a platform-independent format:  a number that represents milliseconds since midnight on 1 January 1970 UTC.  There are methods to convert this to something more useful to you.  You can also manipulate the Date object to set a date or time.

To obtain the current date and time, you should declare a variable as a new Date object.  This will capture and freeze the date and time at that moment in the variable.

var dt = new Date();

When you use a date object, its output will be a string, even though it is an object.  You don't have to convert it prior to displaying it.

We interrupt to note that while the example above
was dynamically created to reflect YOUR time,
all the ones below are static; so references to
Eastern Daylight Time are only because of
my location and the date of example runs.

Declaring a Date and Time

You can also use the Date object to create a date and time for you in multiple ways.  Except for ISO and UTC formats, dates will be assumed to be in local time.

First, you can specify 7 numbers as operands:  year, month, day, hour, minute, second, and millisecond.  The less you specify, the more defaults are filled in as zero.  Example:

var startDate = new Date(2020, 8, 12, 10, 30, 45, 0);
// returns:  Sat Sep 12 2020 10:30:45 GMT-0400 (Eastern Daylight Time)
var startDate = new Date(2020, 8, 12);
// returns:  Sat Sep 12 2020 00:00:00 GMT-0400 (Eastern Daylight Time)

NOTE!  Rather horribly, JavaScript counts months starting with 0, so every programmer in the world has to adjust for this!  So the 8 above stands for the 9th month, September.

Second, you can specify what is called a short date:  mm/dd/yy.  To protect yourself from browser oddities, use leading zeroes!

var dtshort = new Date("01/01/2020");
// returns:  Wed Jan 01 2020 00:00:00 GMT-0500 (Eastern Standard Time)

Third, you can specify what is called a long date:  mmm dd yyyy.  Turns out the operands are very flexible:  you can abbreviate month or not; you can change the order of the month and day; and commas and case are ignored.

var dtlong = new Date("Jun 10 2020");
var dtlong = new Date("june 10, 2020");
var dtlong = new Date("10 JUNE 2020");
// all return:  Wed Jun 10 2020 00:00:00 GMT-0400 (Eastern Daylight Time)

Fourth, you can specify dates in ISO format (International Standards Organization); however, the date you specify will assumed to be UTC, and the output will, as usual, be converted to local time, so be careful.  You only need to specify year, but more typically you would specify year-month-day.  If you want to include the time, add T12:00:00Z immediately following.  The Z indicates UTC.  Alternatively, you can replace the Z with +HH:MM or -HH:MM instead.

var dateISO = new Date("2020-09-01");
// returns:  Mon Aug 31 2020 20:00:00 GMT-0400 (Eastern Daylight Time)
var dateISO = new Date("2020-09-01T12:00:00Z");
// returns:  Tue Sep 01 2020 08:00:00 GMT-0400 (Eastern Daylight Time)
var dateISO = new Date("2020-09-01T12:00:00-04:00");
// returns:  Tue Sep 01 2020 12:00:00 GMT-0400 (Eastern Daylight Time)

Display Date Methods

The toDateString method will truncate and display a date as day mmm dd yyyy.  Various other date and time formats are as shown below.  Please NOTE:  since these are methods, you must suffix them with ().

var dt = new Date();    // examples are static, not dynamic
dt.toDateString();      // = Sat Sep 12 2020
dt.toTimeString();      // = 20:23:37 GMT-0400 (Eastern Daylight Time)
dt.toLocaleDateString() // = 9/12/2020 [note Locale, not Local]
dt.toLocaleTimeString() // = 8:23:37 PM	
dt.toLocaleString()     // = 9/12/2020, 8:23:37 PM
dt.toISOString();       // = 2020-09-13T00:23:37.546Z
dt.toUTCString();       // = Sun, 13 Sep 2020 00:23:37 GMT

Note that some of these methods take optional operands.  For instance, while the ones with "locale" in them default to your locale, you can use the operand field to force the conventions of a different locale.

Using toLocaleString for Dates

While the toLocaleString method can be used for more than Dates, you may find it particularly useful for quickly accessing the particular date format you desire.  One you have your date object, you simply attach the toLocaleString method to it, optionally passing along two parameters:

Here are several examples:

var dt = new Date(); // get today's date
dt.toLocaleString(); // = 1/7/2021, 6:28:24 PM
dt.toLocaleString("en-US", { dateStyle: 'medium' }); // = Jan 7, 2021
dt.toLocaleString("en-US", { dateStyle: 'short' });  // = 1/7/21
dt.toLocaleString("en-US", { dateStyle: 'long', timeStyle: 'short' }); // = January 7, 2021 at 8:17 PM EST
dt.toLocaleString("en-US", { dateStyle: 'long', timeStyle: 'long' });  // = January 7, 2021 at 8:16:51 PM EST

Get Date Methods

If you don't like any of the built-in display formats above, you can create your own by using the following methods:

var dt = new Date();
dt.getFullYear();       // Get the year as a four digit number (yyyy)
dt.getMonth();          // Get the month as a number (0-11)
dt.getDay();            // Get the weekday as a number (0-6; 0=Sunday)
dt.getDate();           // Get the day as a number (1-31)
dt.getHours();          // Get the hour (0-23)
dt.getMinutes();        // Get the minute (0-59)
dt.getSeconds();        // Get the second (0-59)
dt.getMilliseconds();   // Get the millisecond (0-999)
dt.getTime();           // Get the time in milliseconds since January 1, 1970
dt.getTimezoneOffset(); // Returns the time difference between UTC time and local time, in minutes;             // Get the time in milliseconds since January 1, 1970

You can insert UTC after "get" above to return the UTC values.  You can replace "get" with "set" to set any value.  NOTE:  There is parse method, but it is not recommended.

# # # # #