Tutorial: Working with Dates
Level: Intermediate. Published on 19 November 2002 in JavaScript
This tutorial describes JavaScript's Date object, and shows how you can use it to manipulate dates. Also included is a simple script to display today's date on your web page. Very handy!
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 |
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) |
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.
Share and enjoy
If you liked this article, you can share it with others by adding it to any of the following social bookmarking sites:
Link to this page
Feel free to link to this article in your own Web pages. Click one of the boxes below to select the text, then copy and paste it into your page:
Keep in touch
Subscribe to our feed or follow us on Twitter for news of our latest articles and other fun stuff.
Also, don't forget the free ELATED Extra Newsletter, where you can get more great Web-building articles and tips sent straight to your inbox!
If you need help with a Web-building issue, check out our online Help Forums, where you can get assistance from members of Elated and other webmasters.
If you would like to offer us feedback on this or any of our articles, please contact us. Have fun!
