new Date()
Create a Date object from the current time, a timestamp, a string, or calendar components.
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()- Added in JavaScript ES1
Parameters
| Parameter | Type | Description |
|---|---|---|
$valueoptional | number | A timestamp: an integer number of milliseconds since the epoch, midnight at the start of 1 January 1970 UTC. Negative values are times before the epoch. |
$dateStringoptional | string | A date string parsed by the same algorithm as Date.parse(). The standard format is the ISO 8601 date time string format, e.g. "1995-12-17T03:24:00". |
$dateObjectoptional | Date | An existing Date object; its timestamp is copied into the new object. |
$yearoptional | number | The year. Integers 0 to 99 map to 1900 to 1999; every other value is the literal year. |
$monthIndexoptional | number | The month as a zero-based index, 0 for January through 11 for December. |
$dayoptional | number= 1 | The day of the month. |
$hoursoptional | number= 0 | The hour of the day, 0 to 23. |
$minutesoptional | number= 0 | The minutes past the hour. |
$secondsoptional | number= 0 | The seconds past the minute. |
$millisecondsoptional | number= 0 | The milliseconds past the second. |
Return value
DateA new Date object. Called without new, it returns a string instead — the same text as new Date().toString() — and ignores every argument. If the string cannot be parsed, or the resulting timestamp falls outside ±8,640,000,000,000,000 ms, the object is an invalid Date whose valueOf() is NaN.
Errors
Never throws for bad input — an unparsable string or an out-of-range timestamp produces an invalid Date whose getTime() is NaN.
Changelog
- PHP ES5The ISO 8601 date time string format became a required, spec-defined input, so "2024-03-15" parses identically everywhere.
- PHP ES2015A date-time string with no offset, such as "2024-03-15T12:00:00", is interpreted as local time. ES5 treated it as UTC, so old and new engines can disagree by your UTC offset.
- PHP ES2018The output of Date.prototype.toString() was standardized and engines are required to parse it back, making round-tripping reliable.
The constructor has three distinct behaviours depending on what you hand it, and picking the wrong one is where most date bugs start.
Which form to reach for
- No arguments — the current moment. This is the only form that reads the system clock.
- A number — treated as a timestamp in milliseconds. Use this when reading a value out of a database or an API that returns epoch milliseconds. If your source gives seconds, multiply by 1000 first.
- A string — routed through the same algorithm as
Date.parse(). Only the ISO 8601 format is guaranteed; anything else is up to the engine. - Two or more numbers — calendar components in local time. Use Date.UTC() instead when you want the components read as UTC.
What trips people up
A single number is a timestamp, not a year: new Date(2024) is 2 seconds after the epoch, not the year 2024. You need at least two arguments before the component form kicks in.
Components roll over rather than clamp. new Date(2023, 11, 32) is 1 January 2024, and new Date(2024, 0, 0) is 31 December 2023 — a handy trick for finding the last day of a month.
Date objects are mutable. Passing one to new Date(other) gives you a copy, which is what you want before calling any set* method.
Example
When to use it
- Turn an epoch-millisecond timestamp from an API response into a Date you can format
- Build a specific calendar date for a test fixture or a date-range boundary
- Copy an existing Date before mutating it with setDate() or setMonth()
- Find the last day of a month by asking for day 0 of the next one
Frequently asked questions
Why is new Date(2024) not the year 2024?
A single numeric argument is always a timestamp in milliseconds, so new Date(2024) is 2.024 seconds after 1 January 1970. The component form needs at least two arguments — use new Date(2024, 0) for January 2024.
Why does my date shift by a day when I parse a string?
A date-only ISO string like "2024-03-15" is interpreted as UTC midnight, so in any timezone behind UTC it prints as 14 March in local time. Use new Date(2024, 2, 15) to get local midnight instead.
Should I use new Date() or Date() without new?
Always use new. Calling Date() as a plain function returns a string of the current time and ignores every argument you pass, which silently breaks code expecting an object.
More examples
Copy before you mutate
setMonth() mutates in place, so the clone is what keeps start pointing at 1 June. The final check confirms the original is untouched.
const start = new Date(2024, 5, 1);
// new Date(dateObject) clones the timestamp
const end = new Date(start);
end.setMonth(end.getMonth() + 1);
console.log(start.toDateString());
console.log(end.toDateString());
// Without the copy, start would have moved too
console.log(start.getMonth() === 5);Rollover as a calendar tool
Because components normalize rather than clamp, day 0 walks backwards into the previous month. That gives you month lengths, leap years included, with no lookup table.
// Day 0 of a month is the last day of the month before it
function lastDayOfMonth(year, monthIndex) {
return new Date(year, monthIndex + 1, 0).getDate();
}
console.log(lastDayOfMonth(2024, 1)); // February in a leap year
console.log(lastDayOfMonth(2023, 1)); // February in a common year
console.log(lastDayOfMonth(2024, 3)); // April
console.log(new Date(2024, 0, 0).toDateString());The two-digit year trap
new Date(24, 0, 1) is 1924, not 2024 — a legacy rule that only applies to the numeric component form. The zero-padded ISO string is read literally as year 99.
// Years 0-99 are silently shifted into the 1900s
console.log(new Date(99, 0, 1).getFullYear());
console.log(new Date(24, 0, 1).getFullYear());
// Spell out the year to mean it literally
console.log(new Date(2024, 0, 1).getFullYear());
// The ISO string form has no such rule
console.log(new Date("0099-01-01T00:00:00Z").getUTCFullYear());
Discussion