Working with Dates

JavaScript’s Date object makes it easy to handle dates in JavaScript. You can use this object to store dates, convert between date formats, and retrieve the current date and time.

In this tutorial we’ll take a look at using the Date object, and end with a simple example script that displays the current date on the web page!

The Date object

The Date class is used to store and retrieve dates in JavaScript. To create a Date object, we can use any of the following techniques:

new Date ( )

This creates a new Date object with the value of the current date and time on the browser PC. (We’ll use this technique later on to display the current date on the page!) For example:

x = new Date ( );

new Date ( milliseconds )

This creates a new Date object with the date value represented by the number of milliseconds since midnight on Jan 1, 1970. For example:

x = new Date ( 86400000 );

creates a new date object x with a date value of midnight, Jan 2, 1970. (There are 86,400,000 milliseconds in a day!)

new Date ( dateString )

This creates a Date object with the date value represented by a date string in a format recognized by the Date.parse() method. (For more info on Date.parse(), see the “Other Date methods” section below.)

For example:

x = new Date ( "January 6, 1972" );
x = new Date ( "January 6, 1972 16:05:00" );

new Date ( year, month, date )

We can also explicitly pass the year, month and day to the Date constructor. Note that, in JavaScript, months run from 0 to 11, rather than 1 to 12!

For example, to create a new Date object with a value of January 6, 1972:

x = new Date ( 1972, 0, 6 );

new Date ( year, month, date, hour, minute, second )

It’s also possible to specify the time as well as the date when creating the object. So to create a new Date object set to Jan 6, 1972 at 5 minutes past 4 in the afternoon:

x = new Date ( 1972, 0, 6, 16, 5, 0 );

Manipulating dates

Now that we know how to create Date objects, let’s take a look at some of the operations you can perform on them.

Methods to retrieve date values

The following methods all extract information from the Date object:

Method	Description	Example
getFullYear ()	Retrieves the year component of the date as a 4-digit number.	y = x.getFullYear ()
getMonth()	Retrieves the month component of the date as a number from 0 to 11 (0=January, 1=February, etc)	y = x.getMonth()
getDate()	Retrieves the day-of-month component of the date as a number from 1 to 31	y = x.getDate()
getDay()	Retrieves the day of the week component of the date as a number from 0 to 6 (0=Sunday, 1=Monday, etc)	y = x.getDay()
getHours()	Retrieves the hours component of the date as a number from 0 to 23	y = x.getHours()
getMinutes()	Retrieves the minutes component of the date as a number from 0 to 59	y = x.getMinutes()
getSeconds()	Retrieves the seconds component of the date as a number from 0 to 59	y = x.getSeconds()
getMilliseconds()	Retrieves the milliseconds component of the date as a number from 0 to 999	y = x.getMilliseconds()
getTimezoneOffset()	Retrieves the time difference, in minutes, between the computer’s local time and GMT	y = x.getTimezoneOffset()

The following methods are similar to the previous ones, but they work with UTC (Universal Time Coordinated) time, or GMT, rather than the computer’s local time.

About UTC

UTC is a timezone-independent way of storing time values, based on milliseconds since midnight, January 1, 1970 in the GMT timezone. All dates and times are stored internally in JavaScript using UTC. When you use the above, non-UTC functions to get dates and times, JavaScript converts the time back into the local computer’s time locale first. However, the UTC functions below will return times and dates in UTC format instead.

Method	Description	Example
getUTCFullYear ()	Retrieves the year component of the date as a 4-digit number.	y = x.getUTCFullYear ()
getUTCMonth()	Retrieves the month component of the date as a number from 0 to 11 (0=January, 1=February, etc)	y = x.getUTCMonth()
getUTCDate()	Retrieves the day-of-month component of the date as a number from 1 to 31	y = x.getUTCDate()
getUTCDay()	Retrieves the day of the week component of the date as a number from 0 to 6 (0=Sunday, 1=Monday, etc)	y = x.getUTCDay()
getUTCHours()	Retrieves the hours component of the date as a number from 0 to 23	y = x.getUTCHours()
getUTCMinutes()	Retrieves the minutes component of the date as a number from 0 to 59	y = x.getUTCMinutes()
getUTCSeconds()	Retrieves the seconds component of the date as a number from 0 to 59	y = x.getUTCSeconds()
getUTCMilliseconds()	Retrieves the milliseconds component of the date as a number from 0 to 999	y = x.getUTCMilliseconds()

Methods to set date values

The following methods allow you to set components of the Date object:

Method	Description	Example
setFullYear()	Sets the year component of the date using a 4-digit number.	x.setFullYear(2002)
setMonth()	Sets the month component of the date using a number from 0 to 11 (0=January, 1=February, etc)	x.setMonth(11)
setDate()	Sets the day-of-month component of the date using a number from 1 to 31	x.setDate(17)
setHours()	Sets the hours component of the date using a number from 0 to 23	x.setHours(20)
setMinutes()	Sets the minutes component of the date using a number from 0 to 59	x.setMinutes(45)
setSeconds()	Sets the seconds component of the date using a number from 0 to 59	x.setSeconds(0)
setMilliseconds()	Sets the milliseconds component of the date using a number from 0 to 999	x.setMilliseconds(500)

And again, these methods set date components using UTC, rather than the computer’s local time:

Method	Description	Example
setUTCFullYear()	Sets the year component of the date using a 4-digit number.	x.setUTCFullYear(2002)
setUTCMonth()	Sets the month component of the date using a number from 0 to 11 (0=January, 1=February, etc)	x.setUTCMonth(11)
setUTCDate()	Sets the day-of-month component of the date using a number from 1 to 31	x.setUTCDate(17)
setUTCHours()	Sets the hours component of the date using a number from 0 to 23	x.setUTCHours(20)
setUTCMinutes()	Sets the minutes component of the date using a number from 0 to 59	x.setUTCMinutes(45)
setUTCSeconds()	Sets the seconds component of the date using a number from 0 to 59	x.setUTCSeconds(0)
setUTCMilliseconds()	Sets the milliseconds component of the date using a number from 0 to 999	x.setUTCMilliseconds(500)

Other Date methods

There is a handful of further methods that can be used on Date objects:

Method	Description	Example
parse()	Converts a date text string to the “milliseconds since midnight Jan 1, 1970” format. You call it using Date.parse() rather than object.parse().	x = Date.parse ("January 6, 1972")
UTC(y, m, d, h, m, s)	Converts the specified date to the “milliseconds since midnight Jan 1, 1970” format. You call it using Date.UTC() rather than object.UTC().	x = Date.UTC(1972, 0, 6) x = Date.UTC (1972, 0, 6, 16, 5, 0)
toString()	Outputs the value of the Date object as a date text string.	y = x.toString()
toUTCString()	Outputs the value of the Date object as a date text string, using UTC.	y = x.toUTCString()
toLocaleString()	Outputs the value of the Date object as a date text string, using the computer’s locale conventions (e.g. D/M/Y for UK computers).	y = x.toLocaleString()
toDateString()	Outputs the “date” portion of the Date object as a text string.	y = x.toDateString()
toTimeString()	Outputs the “time” portion of the Date object as a text string.	y = x.toTimeString()

As you can see, there are lots of methods to help you work with dates! There are actually a few more obscure ones, but we’ve just listed the most useful ones here.

A simple example

In this example, we’ll write a script that you can use to display the current date on your pages.

To try it out, view this page! (Press your browser’s Back button to return here.)

The first thing we’ll need to do is create a new Date object that stores the current date and time. You’ll remember that we can do this very easily:

var current_date = new Date ( );

We could just use the toDateString() method to extract the date portion of current_date, but the results aren’t that pretty!

Fri Nov 15 2002

Instead, we’ll use getFullYear(), getMonth(), getDate() and getDay() to extract the relevant components from the Date object. We can convert the results of getMonth() and getDay() from numbers to names using a couple of arrays.

Here’s the whole script:

<script language="JavaScript">
<!--
var current_date = new Date ( );

var month_names = new Array ( );
month_names[month_names.length] = "January";
month_names[month_names.length] = "February";
month_names[month_names.length] = "March";
month_names[month_names.length] = "April";
month_names[month_names.length] = "May";
month_names[month_names.length] = "June";
month_names[month_names.length] = "July";
month_names[month_names.length] = "August";
month_names[month_names.length] = "September";
month_names[month_names.length] = "October";
month_names[month_names.length] = "November";
month_names[month_names.length] = "December";

var day_names = new Array ( );
day_names[day_names.length] = "Sunday";
day_names[day_names.length] = "Monday";
day_names[day_names.length] = "Tuesday";
day_names[day_names.length] = "Wednesday";
day_names[day_names.length] = "Thursday";
day_names[day_names.length] = "Friday";
day_names[day_names.length] = "Saturday";

document.write ( day_names[current_date.getDay()] );
document.write ( ", " );
document.write ( month_names[current_date.getMonth()] );
document.write ( " " + current_date.getDate() );
document.write ( " " );
document.write ( " " + current_date.getFullYear() );
// -->
</script>

Now we get a much prettier-looking string!

Friday, November 15 2002

Feel free to copy and paste the above script and use it in your own pages. Just insert it in the page where you want the date to appear.

We’ve now looked at the Date object and its methods, and shown how to store, retrieve and manipulate dates. We’ve also included a simple example to show how it all hangs together.