JavaScript Date Objects
JavaScript Date Objects let us work with dates:
Examples
Note
Date objects are static. The «clock» is not «running».
The computer clock is ticking, date objects are not.
JavaScript Date Output
By default, JavaScript will use the browser’s time zone and display a date as a full text string:
You will learn much more about how to display dates, later in this tutorial.
Creating Date Objects
Date objects are created with the new Date() constructor.
There are 9 ways to create a new date object:
new Date()
new Date(date string)
new Date(year,month)
new Date(year,month,day)
new Date(year,month,day,hours)
new Date(year,month,day,hours,minutes)
new Date(year,month,day,hours,minutes,seconds)
new Date(year,month,day,hours,minutes,seconds,ms)
JavaScript new Date()
new Date() creates a date object with the current date and time:
Example
new Date(date string)
new Date(date string) creates a date object from a date string:
Examples
Date string formats are described in the next chapter.
new Date(year, month, . )
new Date(year, month, . ) creates a date object with a specified date and time.
7 numbers specify year, month, day, hour, minute, second, and millisecond (in that order):
Example
Note
JavaScript counts months from 0 to 11:
Specifying a month higher than 11, will not result in an error but add the overflow to the next year:
Specifying a day higher than max, will not result in an error but add the overflow to the next month:
Using 6, 4, 3, or 2 Numbers
6 numbers specify year, month, day, hour, minute, second:
Example
5 numbers specify year, month, day, hour, and minute:
Example
4 numbers specify year, month, day, and hour:
Example
3 numbers specify year, month, and day:
Example
2 numbers specify year and month:
Example
You cannot omit month. If you supply only one parameter it will be treated as milliseconds.
Example
Previous Century
One and two digit years will be interpreted as 19xx:
Example
Example
JavaScript Stores Dates as Milliseconds
JavaScript stores dates as number of milliseconds since January 01, 1970.
Zero time is January 01, 1970 00:00:00 UTC.
One day (24 hours) is 86 400 000 milliseconds.
Now the time is: milliseconds past January 01, 1970
new Date(milliseconds)
new Date(milliseconds) creates a new date object as milliseconds plus zero time:
Examples
01 January 1970 plus 100 000 000 000 milliseconds is:
January 01 1970 minus 100 000 000 000 milliseconds is:
January 01 1970 plus 24 hours is:
01 January 1970 plus 0 milliseconds is:
Date Methods
When a date object is created, a number of methods allow you to operate on it.
Date methods allow you to get and set the year, month, day, hour, minute, second, and millisecond of date objects, using either local time or UTC (universal, or GMT) time.
Date methods and time zones are covered in the next chapters.
Displaying Dates
JavaScript will (by default) output dates using the toString() method. This is a string representation of the date, including the time zone. The format is specified in the ECMAScript specification:
Example
When you display a date object in HTML, it is automatically converted to a string, with the toString() method.
Example
The toDateString() method converts a date to a more readable format:
Example
The toUTCString() method converts a date to a string using the UTC standard:
Example
The toISOString() method converts a date to a string using the ISO standard:
Example
Complete JavaScript Date Reference
For a complete Date reference, go to our:
The reference contains descriptions and examples of all Date properties and methods.
Date() constructor
The Date() constructor creates Date objects. When called as a function, it returns a string representing the current time.
Try it
Syntax
new Date() new Date(value) new Date(dateString) new Date(dateObject) new Date(year, monthIndex) new Date(year, monthIndex, day) new Date(year, monthIndex, day, hours) new Date(year, monthIndex, day, hours, minutes) new Date(year, monthIndex, day, hours, minutes, seconds) new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds) Date()
Note: Date() can be called with or without new , but with different effects. See Return value.
Parameters
There are five basic forms for the Date() constructor:
No parameters
When no parameters are provided, the newly-created Date object represents the current date and time as of the time of instantiation. The returned date’s timestamp is the same as the number returned by Date.now() .
Time value or timestamp number
An integer value representing the timestamp (the number of milliseconds since midnight at the beginning of January 1, 1970, UTC — a.k.a. the epoch).
Date string
A string value representing a date, parsed and interpreted using the same algorithm implemented by Date.parse() . See date time string format for caveats on using different formats.
Date object
An existing Date object. This effectively makes a copy of the existing Date object with the same date and time. This is equivalent to new Date(dateObject.valueOf()) , except the valueOf() method is not called.
When one parameter is passed to the Date() constructor, Date instances are specially treated. All other values are converted to primitives. If the result is a string, it will be parsed as a date string. Otherwise, the resulting primitive is further coerced to a number and treated as a timestamp.
Individual date and time component values
Given at least a year and month, this form of Date() returns a Date object whose component values (year, month, day, hour, minute, second, and millisecond) all come from the following parameters. Any missing fields are given the lowest possible value ( 1 for day and 0 for every other component). The parameter values are all evaluated against the local time zone, rather than UTC. Date.UTC() accepts similar parameters but interprets the components as UTC and returns a timestamp.
If any parameter overflows its defined bounds, it «carries over». For example, if a monthIndex greater than 11 is passed in, those months will cause the year to increment; if a minutes greater than 59 is passed in, hours will increment accordingly, etc. Therefore, new Date(1990, 12, 1) will return January 1st, 1991; new Date(2020, 5, 19, 25, 65) will return 2:05 A.M. June 20th, 2020.
Similarly, if any parameter underflows, it «borrows» from the higher positions. For example, new Date(2020, 5, 0) will return May 31st, 2020.
Integer value representing the year. Values from 0 to 99 map to the years 1900 to 1999 . All other values are the actual year. See the example.
Integer value representing the month, beginning with 0 for January to 11 for December.
Integer value representing the day of the month. Defaults to 1 .
Integer value between 0 and 23 representing the hour of the day. Defaults to 0 .
Integer value representing the minute segment of a time. Defaults to 0 .
Integer value representing the second segment of a time. Defaults to 0 .
Integer value representing the millisecond segment of a time. Defaults to 0 .
Return value
Calling new Date() (the Date() constructor) returns a Date object. If called with an invalid date string, or if the date to be constructed will have a timestamp less than -8,640,000,000,000,000 or greater than 8,640,000,000,000,000 milliseconds, it returns an invalid date (a Date object whose toString() method returns «Invalid Date» and valueOf() method returns NaN ).
Calling the Date() function (without the new keyword) returns a string representation of the current date and time, exactly as new Date().toString() does. Any arguments given in a Date() function call (without the new keyword) are ignored; regardless of whether it’s called with an invalid date string — or even called with any arbitrary object or other primitive as an argument — it always returns a string representation of the current date and time.
Examples
Several ways to create a Date object
The following examples show several ways to create JavaScript dates:
const today = new Date(); const birthday = new Date("December 17, 1995 03:24:00"); // DISCOURAGED: may not work in all runtimes const birthday = new Date("1995-12-17T03:24:00"); // This is standardized and will work reliably const birthday = new Date(1995, 11, 17); // the month is 0-indexed const birthday = new Date(1995, 11, 17, 3, 24, 0); const birthday = new Date(628021800000); // passing epoch timestamp
Passing a non-Date, non-string, non-number value
If the Date() constructor is called with one parameter which is not a Date instance, it will be coerced to a primitive and then checked whether it’s a string. For example, new Date(undefined) is different from new Date() :
.log(new Date(undefined)); // Invalid Date
This is because undefined is already a primitive but not a string, so it will be coerced to a number, which is NaN and therefore not a valid timestamp. On the other hand, null will be coerced to 0 .
.log(new Date(null)); // 1970-01-01T00:00:00.000Z
Arrays would be coerced to a string via Array.prototype.toString() , which joins the elements with commas. However, the resulting string for any array with more than one element is not a valid ISO 8601 date string, so its parsing behavior would be implementation-defined. Do not pass arrays to the Date() constructor.
.log(new Date(["2020-06-19", "17:13"])); // 2020-06-19T17:13:00.000Z in Chrome, since it recognizes "2020-06-19,17:13" // "Invalid Date" in Firefox
Specifications
Browser compatibility
BCD tables only load in the browser
See also
Found a content problem with this page?
This page was last modified on Jun 1, 2023 by MDN contributors.
Your blueprint for a better internet.
MDN
Support
Our communities
Developers
Visit Mozilla Corporation’s not-for-profit parent, the Mozilla Foundation.
Portions of this content are ©1998– 2023 by individual mozilla.org contributors. Content available under a Creative Commons license.