Dates

Anonymous contributor's avatar
Anonymous contributor
Anonymous contributor's avatar
Anonymous contributor
Published Jul 30, 2021Updated Sep 5, 2023
Contribute to Docs

In JavaScript, Date objects represent a single moment in time stored as a representation of the number of milliseconds since midnight on January 1st, 1970 UTC.

Note: This is different from a UNIX timestamp, which is the number of seconds since the Epoch (Midnight UTC on January 1st, 1970). Even though the representation of a Date is in UTC, the methods to fetch a date or its components work in the host system’s local time zone (which may differ from UTC).

Syntax

const myDate = new Date(dateValue);

The dateValue can be any of the following:

  • It can be a string representation of a date that is valid and IETF-compliant.
  • It can be another instance of the Date class.
  • It can be an integer that represents the date measured in milliseconds since January 1st, 1970 UTC.

The defined range for a Date value is between April 20, 271821 BCE to September 13, 275760 CE. Individual datetime elements can be defined in the Date() constructor with the following syntax:

const d = new Date(year, month, day, hour, minute, second, millisecond);

Date Format Types

In JavaScript, the following three date format types are commonly used:

Format Type Syntax
ISO Date (The International Standard) new Date("YYYY-MM-DDThh:mm:ss.sssZ)
Short Date new Date("YYYY-MM-DD") / new Date("YYYY/MM/DD")
Long Date new Date("Mon DD YYYY") ( or "DD Month YYYY")

With regard to ISO dates:

  • It is the only format that is strictly enforced while the others may vary in functionality depending on the browser.
  • “YYYY-MM-DD” or “YYYY/MM/DD” is the preferred format.
  • In the output, the T separates the date from the time while the Z represents the UTC timezone.
  • Existing dates can be converted to ISO with the .toISOString() method.

With regard to short dates:

  • It is best practice to use leading zeros when referring to single-digit calendar days.
  • If using “YYYY-MM-DD” returns NaN the alternative format “YYYY/MM/DD” should be tested (and vice versa).

With regard to long dates:

  • The day and month can be in any order.
  • The month can either be abbreviated (“Mar”) or written in full (“March”).
  • Names are case-sensitive and commas can be ignored. (e.g. new Date("MONTH DD YYYY"))

Example

When used as a function, Date() returns the current date and time. When used as a constructor, Date() returns a new date object.

const now = Date();
console.log(now);
const then = new Date();
console.log(then);

The output from the snippet above would look similar to this:

Fri Apr 22 2022 17:59:19 GMT+0000 (Coordinated Universal Time)
2022-04-22T17:59:19.244Z

Codebyte Example

The example below defines a new Date object d. Many instance methods are used, which can be found at the bottom of this entry.

Code
Output
Loading...

Dates

.getDate()
Returns the day of the month.
.getDay()
Returns the day of the week.
.getFullYear()
Returns the four digit year for the given date.
.getHours()
Returns the hours of a date according to the local time.
.getMilliseconds()
Returns the milliseconds of a date according to the local time.
.getMinutes()
Called from an instance of the Date class, will return the minutes according to the local time.
.getMonth()
Called from an instance of the Date class, will return the month of the year.
.getSeconds()
Called from an instance of the Date class, will return the seconds according to the local time.
.getTime()
Returns the number of milliseconds since the 1st of January 1970.
.getTimezoneOffset()
Returns the time zone offset in minutes between the local time and UTC.
.getUTCDate()
Returns the day of the month for the provided date.
.getUTCDay()
Returns the day of the week in the specified date according to universal time.
.getUTCFullYear()
Returns the year of the specified date according to universal time.
.getUTCHours()
Returns the hours of a provided date according to universal time.
.getUTCMilliseconds()
Returns the milliseconds for a passed date according to universal time.
.getUTCMinutes()
Returns the minutes of the provided date in universal time.
.getUTCMonth()
Returns the month of the passed date according to universal time, as a zero-based value.
.getUTCSeconds()
Returns the seconds (0 to 59) of a date according to universal time.
.now()
Returns the current time in milliseconds. The milliseconds count begins at 1970/01/01 at 00:00:00 UTC.
.setDate()
Changes the day of the month according to local time.
.setFullYear()
Changes the year, month, and/or day according to local time.
.setHours()
Sets the hours for a specified date according to local time.
.setMilliseconds()
Sets the milliseconds of a date.
.setMinutes()
Changes the minute value of a date according to local time.
.setMonth()
Changes the month of a date according to the local time.
.setSeconds()
Sets the seconds component of a date object to a specified value.
.setTime()
Sets the date and time by adding or subtracting a specified number of milliseconds to/from midnight January 1, 1970.
.setUTCDate()
Changes the day of a Date object in Coordinated Universal Time (UTC).
.setUTCFullYear()
Used to set the year value of a Date object in UTC (Coordinated Universal Time).
.setUTCHours()
Sets the hour value of a date object using UTC.
.setUTCMilliseconds()
Sets the milliseconds value of a date object based on Coordinated Universal Time (UTC).
.setUTCMinutes()
Changes the minutes for a given date according to universal time (UTC).
.setUTCMonth()
Sets the month value of a date according to Coordinated Universal Time (UTC).
.setUTCSeconds()
Sets the second value of a date using UTC.
.toDateString()
Returns a string representing the date portion of a Date instance
.toISOString()
Returns a string representation of a date in an ISO 8601-compliant format.
.toJSON()
Returns a string representation of a date in the JavaScript date time string format.
.toLocaleDateString()
Returns a modified string from a given Date object, usually for events. It is translated to a specific language format according to an event locale and other options.
.toString()
Converts a Date object to a string.
.toTimeString()
Returns the time portion of the given Date object.
.toUTCString()
Converts a date object to a string, according to UTC.
.UTC()
Returns a number value representing the number of milliseconds between the specified date and January 1, 1970, 00:00:00, Universal Time Coordinated. Will always be called as Date.UTC() rather than called on an instance of date such as myDate.UTC().
.valueOf()
Returns the difference in milliseconds between the specified date and January 1, 1970 00:00:00 UTC.

All contributors

Looking to contribute?

Learn JavaScript on Codecademy