JavaScript Note: TC39 is working on Temporal, a new Date/Time API. Read more about it on the
Igalia blog. It is not yet ready for production use! A JavaScript date is fundamentally specified as the number of milliseconds that have elapsed since the
ECMAScript epoch, which is defined as January 1, 1970, UTC [equivalent to the UNIX epoch]. Note: It's important to keep in mind that while the time value at the heart of a Date object is UTC, the basic methods to fetch the date and time or its components
all work in the local [i.e. host system] time zone and offset. It should be noted that the maximum There are several methods available to obtain a date in various formats, as well as to perform time zone
conversions. Particularly useful are the functions that output the date and time in Coordinated Universal Time [UTC], the global standard time defined by the World Time Standard. [This time is historically known as Greenwich Mean Time, as UTC lies along the meridian that includes London—and nearby Greenwich—in the United Kingdom.] The user's device provides the local time. In addition to methods to read and alter individual components of the local date and time [such as
When called as a function, returns a string representation of the current date and time. All arguments are ignored. The result is the same as executing
When called as a constructor, returns a new Returns the numeric value corresponding to the current time—the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC, with leap seconds ignored. Parses a string representation of a date and returns the number of milliseconds since 1 January, 1970, 00:00:00 UTC, with leap seconds ignored. Note: Parsing of strings with Accepts the same parameters as the longest
form of the constructor [i.e. 2 to 7] and returns the number of milliseconds since January 1, 1970, 00:00:00 UTC, with leap seconds ignored. Returns the day of the month [ Returns the day of the week [ Returns the year [4 digits for 4-digit years] of the specified date according to local time. Returns the
hour [Date objects represent a single moment in time in a platform-independent format. Date objects contain a Number that represents milliseconds since 1 January 1970 UTC.Description
The ECMAScript epoch and timestamps
Date is not of the same value as the maximum safe integer [Number.MAX_SAFE_INTEGER is 9,007,199,254,740,991]. Instead, it is defined in ECMA-262 that a maximum of ±100,000,000 [one hundred million] days relative to January 1, 1970 UTC [that is, April 20, 271821 BCE ~ September 13, 275760 CE] can be represented by the standard Date object [equivalent to ±8,640,000,000,000,000 milliseconds].Date format and time zone conversions
getDay[] and setHours[]], there are also versions of the same methods that read and manipulate the date and time using UTC [such as
getUTCDay[] and setUTCHours[]].Constructor
Date[]new Date[].toString[].new Date[]Date object.Static
methods
Date.now[]Date.parse[]
Date.parse is strongly discouraged due to browser differences and inconsistencies.Date.UTC[]Instance methods
Date.prototype.getDate[]1–31] for the specified date according to local time.Date.prototype.getDay[]0–6] for the specified date according
to local time.Date.prototype.getFullYear[]Date.prototype.getHours[]0–23] in the specified date according to local time.
Date.prototype.getMilliseconds[]Returns the milliseconds [0–999] in the specified date according to local time.
Date.prototype.getMinutes[]Returns the minutes [0–59] in the specified date according to local time.
Date.prototype.getMonth[]Returns the month [0–11] in the specified date according to local
time.
Date.prototype.getSeconds[]Returns the seconds [0–59] in the specified date according to local time.
Date.prototype.getTime[]Returns the numeric value of the specified date as the number of milliseconds since January 1, 1970, 00:00:00 UTC. [Negative values are returned for prior times.]
Date.prototype.getTimezoneOffset[]Returns the time-zone offset in minutes for the current locale.
Date.prototype.getUTCDate[]Returns the day [date] of the month [1–31] in the specified date according to universal time.
Date.prototype.getUTCDay[]Returns the day of the week [0–6] in the
specified date according to universal time.
Date.prototype.getUTCFullYear[]Returns the year [4 digits for 4-digit years] in the specified date according to universal time.
Date.prototype.getUTCHours[]Returns the hours [0–23] in the specified date according to universal time.
Date.prototype.getUTCMilliseconds[]Returns the milliseconds [0–999] in the
specified date according to universal time.
Date.prototype.getUTCMinutes[]Returns the minutes [0–59] in the specified date according to universal time.
Date.prototype.getUTCMonth[]Returns the month [0–11] in the specified date according to universal time.
Date.prototype.getUTCSeconds[]Returns the seconds
[0–59] in the specified date according to universal time.
Date.prototype.getYear[] DeprecatedReturns the year [usually 2–3 digits] in the specified date according to local time. Use
getFullYear[] instead.
Date.prototype.setDate[]Sets the day of the month for a specified date according to local time.
Date.prototype.setFullYear[]Sets the full year [e.g. 4 digits for 4-digit years] for a specified date according to local time.
Date.prototype.setHours[]Sets the hours for a specified date according to local time.
Date.prototype.setMilliseconds[]Sets the milliseconds for a specified date according to local time.
Date.prototype.setMinutes[]Sets the minutes for a specified date according to local time.
Date.prototype.setMonth[]Sets the month for a specified date according to local time.
Date.prototype.setSeconds[]Sets the seconds for a specified date according to local time.
Date.prototype.setTime[]Sets the Date object to the time represented by a number of milliseconds since January 1, 1970, 00:00:00 UTC. Use negative numbers for times prior.
Date.prototype.setUTCDate[]Sets the day of the month for a specified date according to universal time.
Date.prototype.setUTCFullYear[]Sets the full year [e.g. 4 digits for 4-digit years] for a specified date according to universal time.
Date.prototype.setUTCHours[]Sets the hour for a specified date according to universal time.
Date.prototype.setUTCMilliseconds[]Sets the milliseconds for a specified date according to universal time.
Date.prototype.setUTCMinutes[]Sets the minutes for a specified date according to universal time.
Date.prototype.setUTCMonth[]Sets the month for a specified date according to universal time.
Date.prototype.setUTCSeconds[]Sets the seconds for a specified date according to universal time.
Date.prototype.setYear[] DeprecatedSets the year [usually 2–3 digits] for a specified date according to local time. Use
setFullYear[] instead.
Date.prototype.toDateString[]Returns the "date" portion of the
Date as a human-readable string like 'Thu Apr 12 2018'.
Date.prototype.toISOString[]Converts a date to a string following the ISO 8601 Extended Format.
Date.prototype.toJSON[]Returns a string representing the Date using toISOString[]. Intended for use by
JSON.stringify[].
Date.prototype.toGMTString[] DeprecatedReturns a string representing the
Date based on the GMT [UTC] time zone. Use toUTCString[] instead.
Date.prototype.toLocaleDateString[]Returns a string with a locality sensitive representation of the date portion of this date based on system settings.
Date.prototype.toLocaleString[]Returns a string with a
locality-sensitive representation of this date. Overrides the Object.prototype.toLocaleString[] method.
Date.prototype.toLocaleTimeString[]Returns a string with a locality-sensitive representation of the time portion of this date, based on system settings.
Date.prototype.toString[]Returns a string representing the specified Date object. Overrides the
Object.prototype.toString[] method.
Date.prototype.toTimeString[]Returns the "time" portion of the
Date as a human-readable string.
Date.prototype.toUTCString[]Converts a date to a string using the UTC timezone.
Date.prototype.valueOf[]Returns the primitive value of a Date object. Overrides the Object.prototype.valueOf[] method.
Examples
Several ways to create a Date object
The following examples show several ways to create JavaScript dates:
Note: When parsing date strings with the Date constructor [and Date.parse, they are equivalent], always make sure that the input conforms to the ISO 8601 format [YYYY-MM-DDTHH:mm:ss.sssZ] — the parsing behavior with other formats is implementation-defined and may not work across all browsers. A library can help if many different formats are to be accommodated.
const today = new Date[]
const birthday = new Date['December 17, 1995 03:24:00'] // DISCOURAGED: may not work in all runtimes
const birthday2 = new Date['1995-12-17T03:24:00'] // This is ISO8601-compliant and will work reliably
const birthday3 = new Date[1995, 11, 17] // the month is 0-indexed
const birthday4 = new Date[1995, 11, 17, 3, 24, 0]
const birthday5 = new Date[628021800000] // passing epoch timestamp
Formats of toString method return values
const date = new Date["2020-05-12T23:50:21.817Z"];
date.toString[] // Tue May 12 2020 18:50:21 GMT-0500 [Central Daylight Time]
date.toDateString[] // Tue May 12 2020
date.toTimeString[] // 18:50:21 GMT-0500 [Central Daylight Time]
date.toISOString[] // 2020-05-12T23:50:21.817Z
date.toUTCString[] // Tue, 12 May 2020 23:50:21 GMT
date.toGMTString[] // Tue, 12 May 2020 23:50:21 GMT
date.toJSON[] // 2020-05-12T23:50:21.817Z
date.toLocaleString[] // 5/12/2020, 6:50:21 PM
date.toLocaleDateString[] // 5/12/2020
date.toLocaleTimeString[] // 6:50:21 PM
To get Date, Month and Year or Time
const date = new Date[];
const [month, day, year] = [date.getMonth[], date.getDate[], date.getFullYear[]];
const [hour, minutes, seconds] = [date.getHours[], date.getMinutes[], date.getSeconds[]];
Interpretation of two-digit years
new Date[] exhibits legacy undesirable, inconsistent behavior with two-digit year values; specifically, when a new Date[] call is given a two-digit year value, that year value does not get treated as a literal year and used as-is but instead gets
interpreted as a relative offset — in some cases as an offset from the year 1900, but in other cases, as an offset from the year 2000.
let date = new Date[98, 1]; // Sun Feb 01 1998 00:00:00 GMT+0000 [GMT]
date = new Date[22, 1]; // Wed Feb 01 1922 00:00:00 GMT+0000 [GMT]
date = new Date["2/1/22"]; // Tue Feb 01 2022 00:00:00 GMT+0000 [GMT]
// Legacy method; always interprets two-digit year values as relative to 1900
date.setYear[98]; date.toString[]; // Sun Feb 01 1998 00:00:00 GMT+0000 [GMT]
date.setYear[22]; date.toString[]; // Wed Feb 01 1922 00:00:00 GMT+0000 [GMT]
So, to create and get dates between the years 0 and 99, instead use the preferred setFullYear[] and
getFullYear[] methods:.
// Preferred method; never interprets any value as being a relative offset,
// but instead uses the year value as-is
date.setFullYear[98]; date.getFullYear[]; // 98 [not 1998]
date.setFullYear[22]; date.getFullYear[]; // 22 [not 1922, not 2022]
Calculating elapsed time
The following examples show how to determine the elapsed time between two JavaScript dates in milliseconds.
Due to the differing lengths of days [due to daylight saving changeover], months, and years, expressing elapsed time in units greater than hours, minutes, and seconds requires addressing a number of issues, and should be thoroughly researched before being attempted.
// Using Date objects
const start = Date.now[];
// The event to time goes here:
doSomethingForALongTime[];
const end = Date.now[];
const elapsed = end - start; // elapsed time in milliseconds
// Using built-in methods
const start = new Date[];
// The event to time goes here:
doSomethingForALongTime[];
const end = new Date[];
const elapsed = end.getTime[] - start.getTime[]; // elapsed time in milliseconds
// To test a function and get back its return
function printElapsedTime[testFn] {
const startTime = Date.now[];
const result = testFn[];
const endTime = Date.now[];
console.log[`Elapsed time: ${String[endTime - startTime]} milliseconds`];
return result;
}
const yourFunctionReturn = printElapsedTime[yourFunction];
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[].
Get the number of seconds since the ECMAScript Epoch
const seconds = Math.floor[Date.now[] / 1000];
In this case, it's
important to return only an integer—so a simple division won't do. It's also important to only return actually elapsed seconds. [That's why this code uses Math.floor[], and not Math.round[].]
Specifications
| ECMAScript Language Specification # sec-date-objects |
Browser compatibility
BCD tables only load in the browser
See also
Date[]constructor