Working with Dates

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.)

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.

Responses to this article

6 responses (oldest first):

I found this post very useful when first starting out with javascript dates.

Now, having learnt javascript, I want to make a suggestion:when converting the results of getMonth() and getDay() from numbers to names, why not define all elements of the array upon its creation? eg:

var month_names = ["January", "February", etc...]

The code is much nicer.

Furthermore, it seems a really bad way of adding things to array to keep getting its length and then adding a new month to that index. Instead, why not use Javascript's push method (it's much more elegant):

I have date String as dateString="23 juin 2011"(in french locale).when i write myDate = new Date(dateString);it gives undefined/NaN .I want to create Date object for given dateString in given dateFormat(depending on selected locale...) .Is it possible to specify dateFormat(e.g. dd MMM yyyyy) while creating Date object from string?

I'm trying to design an Acrobat PDF form. I'd like to make it impossible for a user to enter a date that is before the date the form is started. Can anyone help me? I'm very much a JavaScript beginner.