Date.prototype.setTime()
Sets a date to a given number of milliseconds since the Unix epoch, replacing its value entirely.
setTime(timeValue)- Added in JavaScript ES1
Parameters
| Parameter | Type | Description |
|---|---|---|
$timeValue | number | An integer representing the new timestamp: the number of milliseconds since midnight at the beginning of 1 January 1970, UTC. |
Return value
numberThe new timestamp of the modified Date object in milliseconds since the epoch — the same value that was passed in. Returns NaN if timeValue is NaN or coerces to NaN, in which case the Date is set to Invalid Date.
setTime() replaces a date's entire value with a timestamp in milliseconds since the epoch. It is the inverse of getTime(), and unlike every other setter it is time-zone-free: the number is absolute, so no local-time or DST reasoning applies.
When to reach for it
- Exact arithmetic.
d.setTime(d.getTime() + 86400000)adds precisely 24 hours.setDate(d.getDate() + 1)adds a calendar day, which is 23 or 25 hours across a DST boundary. When you mean elapsed time, use this. - Reusing an object. Repointing an existing
Dateat a new instant instead of allocating a fresh one, useful inside a hot loop. - Restoring a snapshot. Save
getTime(), mutate freely, thensetTime()back.
What trips people up
The argument is milliseconds. Unix timestamps from APIs and databases are usually in seconds, and passing one directly lands you in January 1970 — multiply by 1000 first.
Passing NaN, undefined, or a value beyond ±8.64e15 does not throw; the date silently becomes Invalid Date and every getter on it returns NaN from then on.
For a new date, new Date(ms) is clearer. Use setTime() when you specifically want to mutate an existing object.
Example
When to use it
- Add an exact number of hours that must not be affected by daylight saving
- Reset a Date back to a saved snapshot after mutating it
- Convert a Unix seconds timestamp from an API into a Date
- Reuse one Date object across many iterations instead of allocating
Frequently asked questions
What is the difference between setTime() and new Date(ms)?
new Date(ms) creates a new object, while setTime() mutates the one you call it on and returns a number. Use the constructor unless you specifically need existing references to the same Date to see the new value.
Why did setTime() put my date in 1970?
Because you passed a Unix timestamp measured in seconds — setTime() expects milliseconds. Multiply the value by 1000 first.
What is the largest value setTime() accepts?
±8,640,000,000,000,000 milliseconds, roughly 273,785 years either side of the epoch. Anything beyond that turns the Date into an Invalid Date and returns NaN rather than throwing.
More examples
Seconds versus milliseconds
Feeding a seconds-based Unix timestamp straight in lands three weeks into 1970 rather than erroring, which is exactly why the bug survives code review. Multiplying by 1000 fixes it.
const unixSeconds = 1717243200; // 1 June 2024, in seconds
const wrong = new Date();
wrong.setTime(unixSeconds);
console.log(wrong.toISOString()); // 1970-01-20T21:00:43.200Z — off by a factor of 1000
const right = new Date();
right.setTime(unixSeconds * 1000);
console.log(right.toISOString()); // 2024-06-01T12:00:00.000ZSnapshot and restore
A single timestamp captures the whole state of a Date, so setTime() restores it in one call regardless of how many fields were changed. The last two lines show the range limit producing an Invalid Date instead of an exception.
const d = new Date("2024-06-01T12:00:00Z");
const snapshot = d.getTime();
d.setUTCFullYear(1999);
d.setUTCMonth(0);
console.log(d.toISOString()); // 1999-01-01T12:00:00.000Z
d.setTime(snapshot); // one call undoes all of it
console.log(d.toISOString()); // 2024-06-01T12:00:00.000Z
d.setTime(8.64e15 + 1); // beyond the representable range
console.log(d.toString()); // Invalid Date
Discussion