Date() constructor
The Date() constructor creates Date objects. When called as a function, it returns a string representing the current time.
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.
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
value- 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
dateString- 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
dateObject- An existingDateobject. This effectively makes a copy of the existingDateobject with the same date and time. This is equivalent tonew Date(dateObject.valueOf()), except thevalueOf()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.
year- Integer value representing the year. Values from0to99map to the years1900to1999. All other values are the actual year. See the example.monthIndex- Integer value representing the month, beginning with0for January to11for December.dayOptional - Integer value representing the day of the month. Defaults to1.hoursOptional - Integer value between0and23representing the hour of the day. Defaults to0.minutesOptional - Integer value representing the minute segment of a time. Defaults to0.secondsOptional - Integer value representing the second segment of a time. Defaults to0.millisecondsOptional - Integer value representing the millisecond segment of a time. Defaults to0.
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.
“Date() constructor - JavaScript | MDN” (MDN Web Docs). Retrieved March 14, 2024.
Date.prototype[@@toPrimitive]()
The [@@toPrimitive]() method of Date instances returns a primitive value representing this date. It may either be a string or a number, depending on the hint given.
The [@@toPrimitive]() method is part of the type coercion protocol. JavaScript always calls the [@@toPrimitive]() method in priority to convert an object to a primitive value. You rarely need to invoke the [@@toPrimitive]() method yourself; JavaScript automatically invokes it when encountering an object where a primitive value is expected.
Syntax
date[Symbol.toPrimitive](hint)
Parameters
hint - A string representing the type of the primitive value to return. The following values are valid:
"string"or"default": The method should return astring."number": The method should return anumber.
Return value
If hint is "string" or "default", this method returns a string by coercing the this value to a string (first trying toString() then trying valueOf()).
If hint is "number", this method returns a number by coercing the this value to a number (first trying valueOf() then trying toString()).
Exceptions
TypeError - Thrown if the hint argument is not one of the three valid values.
Examples:
const d = new Date(0); // 1970-01-01T00:00:00.000Z
d[Symbol.toPrimitive]("string"); // "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)"
d[Symbol.toPrimitive]("number"); // 0
d[Symbol.toPrimitive]("default"); // "Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)"“Date.prototype[@@toPrimitive]() - JavaScript | MDN” (MDN Web Docs). Retrieved March 20, 2024.
Date.prototype.getDate()
The getDate() method of Date instances returns the day of the month for this date according to local time.
Syntax
getDate()
Parameters
None.
Return value
An integer, between 1 and 31, representing the day of the month for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const day = xmas95.getDate();
console.log(day); // 25“Date.prototype.getDate() - JavaScript | MDN” (MDN Web Docs). Retrieved March 20, 2024.
Date.prototype.getDay()
The getDay() method of Date instances returns the day of the week for this date according to local time, where 0 represents Sunday. For the day of the month, see Date.prototype.getDate().
Syntax
getDay()
Parameters
None.
Return value
An integer, between 0 and 6, representing the day of the week for the given date according to local time: 0 for Sunday, 1 for Monday, 2 for Tuesday, and so on. Returns NaN if the date is invalid.
Description
The return value of getDay() is zero-based, which is useful for indexing into arrays of days, for example:
const valentines = new Date("1995-02-14");
const day = valentines.getDay();
const dayNames = ["Sunday", "Monday", "Tuesday" /* , … */];
console.log(dayNames[day]); // "Monday"However, for the purpose of internationalization, you should prefer using Intl.DateTimeFormat with the options parameter instead.
const options = { weekday: "long" };
console.log(new Intl.DateTimeFormat("en-US", options).format(valentines));
// "Monday"
console.log(new Intl.DateTimeFormat("de-DE", options).format(valentines));
// "Montag"Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const weekday = xmas95.getDay();
console.log(weekday); // 1“Date.prototype.getDay() - JavaScript | MDN” (MDN Web Docs). Retrieved March 20, 2024.
Date.prototype.getFullYear()
The getFullYear() method of Date instances returns the year for this date according to local time.
Unlike getYear(), the value returned by getFullYear() is an absolute number. For dates between the years 1000 and 9999, getFullYear() returns a four-digit number, for example, 1995. Use this function to make sure a year is compliant with years after 2000.
Syntax
getFullYear()
Parameters
None.
Return value
An integer representing the year for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const fullYear = xmas95.getFullYear();
console.log(fullYear); // 1995“Date.prototype.getFullYear() - JavaScript | MDN” (MDN Web Docs). Retrieved March 20, 2024.
Date.prototype.getHours()
The getHours() method of Date instances returns the hours for this date according to local time.
Syntax
getHours()
Parameters
None.
Return value
An integer, between 0 and 23, representing the hours for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const hours = xmas95.getHours();
console.log(hours); // 23“Date.prototype.getHours() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getMilliseconds()
The getMilliseconds() method of Date instances returns the milliseconds for this date according to local time.
Syntax
getMilliseconds()
Parameters
None.
Return value
An integer, between 0 and 999, representing the milliseconds for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const milliseconds = xmas95.getMilliseconds();
console.log(milliseconds); // 0“Date.prototype.getMilliseconds() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getMinutes()
The getMinutes() method of Date instances returns the minutes for this date according to local time.
Syntax
getMinutes()
Parameters
None.
Return value
An integer, between 0 and 59, representing the minutes for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const minutes = xmas95.getMinutes();
console.log(minutes); // 15“Date.prototype.getMinutes() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getMonth()
The getMonth() method of Date instances returns the month for this date according to local time, as a zero-based value (where zero indicates the first month of the year).
The return value of getMonth() is zero-based, which is useful for indexing into arrays of months, for example:
Syntax
getMonth()
Parameters
None.
Return value
An integer, between 0 and 11, representing the month for the given date according to local time: 0 for January, 1 for February, and so on. Returns NaN if the date is invalid.
Examples:
const valentines = new Date("1995-02-14");
const month = valentines.getMonth();
const monthNames = ["January", "February", "March" /* , … */];
console.log(monthNames[month]); // "February"“Date.prototype.getMonth() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getSeconds()
The getSeconds() method of Date instances returns the seconds for this date according to local time.
Syntax
getSeconds()
Parameters
None.
Return value
An integer, between 0 and 59, representing the seconds for the given date according to local time. Returns NaN if the date is invalid.
Examples:
const xmas95 = new Date("1995-12-25T23:15:30");
const seconds = xmas95.getSeconds();
console.log(seconds); // 30“Date.prototype.getSeconds() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getTime()
The getTime() method of Date instances returns the number of milliseconds for this date since the epoch, which is defined as the midnight at the beginning of January 1, 1970, UTC.
Date objects are fundamentally represented by a timestamp, and this method allows you to retrieve the timestamp. You can use this method to help assign a date and time to another Date object. This method is functionally equivalent to the valueOf() method.
Reduced time precision
To offer protection against timing attacks and fingerprinting, the precision of new Date().getTime() might get rounded depending on browser settings. In Firefox, the privacy.reduceTimerPrecision preference is enabled by default and defaults to 2ms. You can also enable privacy.resistFingerprinting, in which case the precision will be 100ms or the value of privacy.resistFingerprinting, reduceTimerPrecision.microseconds, whichever is larger.
// reduced time precision (2ms) in Firefox 60 new Date().getTime(); // 1519211809934 // 1519211810362 // 1519211811670 // … // reduced time precision with `privacy.resistFingerprinting` enabled new Date().getTime(); // 1519129853500 // 1519129858900 // 1519129864400 // …
Syntax
getTime()
Parameters
None.
Return value
A number representing the timestamp, in milliseconds, of this date. Returns NaN if the date is invalid.
Examples:
// Since month is zero based, birthday will be January 10, 1995 const birthday = new Date(1994, 12, 10); const copy = new Date(); copy.setTime(birthday.getTime());
Note: In browsers that support the Web Performance API’s high-resolution time feature, Performance.now() can provide more reliable and precise measurements of elapsed time than Date.now().
“Date.prototype.getTime() - JavaScript | MDN” (MDN Web Docs). Retrieved March 21, 2024.
Date.prototype.getTimezoneOffset()
The getTimezoneOffset() method of Date instances returns the difference, in minutes, between this date as evaluated in the UTC time zone, and the same date as evaluated in the local time zone.
Negative values and positive values
The number of minutes returned by getTimezoneOffset() is positive if the local time zone is behind UTC, and negative if the local time zone is ahead of UTC. For example, for UTC+10, -600 will be returned.
Syntax
getTimezoneOffset()
Parameters
None.
Return value
A number representing the difference, in minutes, between the date as evaluated in the UTC time zone and as evaluated in the local time zone. The actual local time algorithm is implementation-defined, and the return value is allowed to be zero in runtimes without appropriate data. Returns NaN if the date is invalid.
Examples:
// Create a Date instance for the current time
const currentLocalDate = new Date();
// Create a Date instance for 03:24 GMT-0200 on May 1st in 2016
const laborDay2016at0324GMTminus2 = new Date("2016-05-01T03:24:00-02:00");
currentLocalDate.getTimezoneOffset() ===
laborDay2016at0324GMTminus2.getTimezoneOffset();
// true, always, in any timezone that doesn't annually shift in and out of DST
// false, sometimes, in any timezone that annually shifts in and out of DST“Date.prototype.getTimezoneOffset() - JavaScript | MDN” (MDN Web Docs). Retrieved March 22, 2024.
Date.prototype.getUTCDate()
The getUTCDate() method of Date instances returns the day of the month for this date according to universal time.
Syntax
getUTCDate()
Parameters
None.
Return value
An integer, between 1 and 31, representing day of month for the given date according to universal time. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const dayOfMonth = today.getUTCDate();
“Date.prototype.getUTCDate() - JavaScript | MDN” (MDN Web Docs). Retrieved March 22, 2024.
Date.prototype.getUTCDay()
The getUTCDay() method of Date instances returns the day of the week for this date according to universal time, where 0 represents Sunday.
Syntax
getUTCDay()
Parameters
None.
Return value
An integer corresponding to the day of the week for the given date according to universal time: 0 for Sunday, 1 for Monday, 2 for Tuesday, and so on. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const weekday = today.getUTCDay();
“Date.prototype.getUTCDay() - JavaScript | MDN” (MDN Web Docs). Retrieved March 22, 2024.
Date.prototype.getUTCFullYear()
The getUTCFullYear() method of Date instances returns the year for this date according to universal time.
Unlike getYear(), the value returned by getUTCFullYear() is an absolute number. For dates between the years 1000 and 9999, getUTCFullYear() returns a four-digit number, for example, 1995. Use this function to make sure a year is compliant with years after 2000.
Syntax
getUTCFullYear()
Parameters
None.
Return value
An integer representing the year for the given date according to universal time. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const year = today.getUTCFullYear();
“Date.prototype.getUTCFullYear() - JavaScript | MDN” (MDN Web Docs). Retrieved March 22, 2024.
Date.prototype.getUTCHours()
The getUTCHours() method of Date instances returns the hours for this date according to universal time.
Syntax
getUTCHours()
Parameters
None.
Return value
An integer, between 0 and 23, representing the hours for the given date according to universal time. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const hours = today.getUTCHours();
“Date.prototype.getUTCHours() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.prototype.getUTCMilliseconds()
The getUTCMilliseconds() method of Date instances returns the milliseconds for this date according to universal time.
Syntax
getUTCMilliseconds()
Parameters
None.
Return value
An integer, between 0 and 999, representing the milliseconds for the given date according to universal time. Returns NaN if the date is invalid.
Not to be confused with the timestamp. To get the total milliseconds since the epoch, use the getTime() method.
Examples:
const today = new Date(); const milliseconds = today.getUTCMilliseconds();
“Date.prototype.getUTCMilliseconds() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.prototype.getUTCMinutes()
The getUTCMinutes() method of Date instances returns the minutes for this date according to universal time.
Syntax
getUTCMinutes()
Parameters
None.
Return value
An integer, between 0 and 59, representing the minutes for the given date according to universal time. Returns NaN if the date is invalid.
Examples
const today = new Date(); const minutes = today.getUTCMinutes();
“Date.prototype.getUTCMinutes() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.prototype.getUTCMonth()
The getUTCMonth() method of Date instances returns the month for this date according to universal time, as a zero-based value (where zero indicates the first month of the year).
Syntax
getUTCMonth()
Parameters
None.
Return value
An integer, between 0 and 11, representing the month for the given date according to universal time: 0 for January, 1 for February, and so on. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const month = today.getUTCMonth();
“Date.prototype.getUTCMonth() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.prototype.getUTCSeconds()
The getUTCSeconds() method of Date instances returns the seconds in the specified date according to universal time.
Syntax
getUTCSeconds()
Parameters
None.
Return value
An integer, between 0 and 59, representing the seconds for the given date according to universal time. Returns NaN if the date is invalid.
Examples:
const today = new Date(); const seconds = today.getUTCSeconds();
“Date.prototype.getUTCSeconds() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.prototype.getYear()
Deprecated: This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards.
The getYear() method of Date instances returns the year for this date according to local time. Because getYear() does not return full years (“year 2000 problem”), it is deprecated and has been replaced by the getFullYear() method.
Syntax
getYear()
Parameters
None.
Return value
An integer representing the year for the given date according to local time, minus 1900. Returns NaN if the date is invalid.
- For years greater than or equal to
2000, the value is100or greater. For example, if the year is2026,getYear()returns126. - For years between and including
1900and1999, the value returned bygetYear()is between0and99. For example, if the year is1976,getYear()returns76. - For years less than
1900, the value returned bygetYear()is less than ç. For example, if the year is1800,getYear()returns-100.
This method essentially returns the value ofgetFullYear()minus1900. You should usegetFullYear()instead, so that the year is specified in full.
Examples:
// Years between 1900 and 1999
let xmas = new Date("1995-12-25");
let year = xmas.getYear(); // returns 95
// Years above 1999
xmas = new Date("2000-12-25");
year = xmas.getYear(); // returns 100
// Years below 1900
xmas = new Date("1800-12-25");
year = xmas.getYear(); // returns -100“Date.prototype.getYear() - JavaScript | MDN” (MDN Web Docs). Retrieved March 25, 2024.
Date.now()
The Date.now() static method returns the number of milliseconds elapsed since the epoch, which is defined as the midnight at the beginning of January 1, 1970, UTC.
Reduced time precision
To offer protection against timing attacks and fingerprinting, the precision of Date.now() might get rounded depending on browser settings.
Syntax
Date.now()
Parameters
None.
Return value
A number representing the timestamp, in milliseconds, of the current time.
“Date.now() - JavaScript | MDN” (MDN Web Docs). Retrieved March 26, 2024.
Date.parse()
The Date.parse() static method parses a string representation of a date, and returns the date’s timestamp.
Syntax
Date.parse(dateString)
Parameters
dateString- A string in the date time string format.
Return value
A number representing the timestamp of the given date. If dateString fails to be parsed as a valid date, NaN is returned.
Examples:
The following calls all return 1546300800000. The first will imply UTC time because it’s date-only, and the others explicitly specify the UTC timezone.
Date.parse("2019-01-01");
Date.parse("2019-01-01T00:00:00.000Z");
Date.parse("2019-01-01T00:00:00.000+00:00");“Date.parse() - JavaScript | MDN” (MDN Web Docs). Retrieved March 26, 2024.
Date.prototype.setDate()
The setDate() method of Date instances changes the day of the month for this date according to local time.
Syntax
setDate(dateValue)
Parameters
dateValue- An integer representing the day of the month.
Return value
Changes the Date object in place, and returns its new timestamp. If dateValue is NaN (or other values that get coerced to NaN, such as undefined), the date is set to Invalid Date and NaN is returned.
Examples:
const theBigDay = new Date(1962, 6, 7, 12); // noon of 1962-07-07 (7th of July 1962, month is 0-indexed) const theBigDay2 = new Date(theBigDay).setDate(24); // 1962-07-24 (24th of July 1962) const theBigDay3 = new Date(theBigDay).setDate(32); // 1962-08-01 (1st of August 1962) const theBigDay4 = new Date(theBigDay).setDate(22); // 1962-07-22 (22nd of July 1962) const theBigDay5 = new Date(theBigDay).setDate(0); // 1962-06-30 (30th of June 1962) const theBigDay6 = new Date(theBigDay).setDate(98); // 1962-10-06 (6th of October 1962) const theBigDay7 = new Date(theBigDay).setDate(-50); // 1962-05-11 (11th of May 1962)
“Date.prototype.setDate() - JavaScript | MDN” (MDN Web Docs). Retrieved March 26, 2024.
-
Basics42
-
Working with Strings21
-
String concepts8
-
Strings API36
-
Operators32
-
Working with Numbers16
-
Math basics22
-
Numbers API13
-
Working with Arrays17
-
Arrays API24
-
Control Flow and Error Handling32
-
Loops and iteration10
-
Working with Functions27
-
Predefined Functions28
-
Functions API16
-
Troubleshooting11
-
Working with Objects17
-
Objects API31
-
Value of "this"16
-
Working with Date built-in object10
-
Date API49
-
Working with Maps and WeakMaps21
-
Map API13
-
WeakMap API6
-
Working with Sets15
-
Set API21
-
Working with ES6 modules22
-
Destructuring17
-
Generators23
-
Classes ES621
-
Regular Expressions35
