Date.prototype.setSeconds()
Sets the seconds, and optionally milliseconds, of a date in local time and returns the new timestamp.
setSeconds(secondsValue)
setSeconds(secondsValue, msValue)- Added in JavaScript ES1
Parameters
| Parameter | Type | Description |
|---|---|---|
$secondsValue | number | An integer between 0 and 59 representing the seconds. Values outside the range shift the minutes and higher units accordingly. |
$msValueoptional | number= this.getMilliseconds() | An integer between 0 and 999 representing the milliseconds. Defaults to the value returned by getMilliseconds(). |
Return value
numberThe new timestamp of the modified Date object in milliseconds since the epoch. Returns NaN if any parameter is NaN or coerces to NaN, in which case the Date is set to Invalid Date.
Changelog
- PHP Modern enginesLocal times landing in a DST gap or ambiguity resolve like Temporal's "compatible" disambiguation: the earlier instant when two exist, and gaps are crossed forward.
setSeconds() writes the seconds onto an existing date in place, optionally taking milliseconds as a second argument, and returns the resulting timestamp.
When to reach for it
- Truncating to whole seconds before comparing timestamps or writing them to a system that stores second precision —
d.setSeconds(d.getSeconds(), 0)clears the milliseconds and nothing else. - Adding a duration expressed in seconds, such as a token lifetime:
d.setSeconds(d.getSeconds() + expiresIn). - Snapping a time to the top of a minute with
setSeconds(0, 0).
What trips people up
The milliseconds are the field people forget. setSeconds(0) zeroes the seconds but leaves .318 milliseconds behind, and two dates that look identical when printed will still fail an equality test. Pass setSeconds(0, 0).
Values above 59 cascade upward rather than throwing: setSeconds(100) adds a minute and sets 40 seconds. That is exactly what makes the add-a-duration idiom safe, but it also means unvalidated input silently changes the minute or the hour instead of erroring.
Because it works in local time, adding seconds across a DST transition changes the wall-clock reading by more than the amount you added. Use setTime() when you need an exact millisecond shift.
Example
When to use it
- Strip milliseconds before comparing two timestamps for equality
- Compute a token expiry from a lifetime given in seconds
- Snap a log entry to the top of the minute
- Truncate to whole seconds for a system that stores Unix seconds
Frequently asked questions
How do I remove milliseconds from a Date?
Call d.setSeconds(d.getSeconds(), 0), which rewrites the seconds with their existing value and zeroes the milliseconds. Passing setSeconds(0) alone zeroes the seconds but leaves the fractional part untouched.
What happens if I pass more than 59 to setSeconds()?
The overflow cascades into the minutes and beyond — setSeconds(100) becomes one minute plus 40 seconds. Nothing throws, which is why d.setSeconds(d.getSeconds() + n) is a safe way to add a duration.
Does setSeconds() return the Date?
No, it returns the new timestamp as a number and mutates the date in place, so it cannot be chained. Keep using the original variable, and clone it with new Date(d) first if you need the unmodified value.
More examples
Milliseconds break equality checks
Two dates printing the same time to the second are still unequal because of the fractional part. Re-setting the seconds with an explicit 0 for milliseconds normalizes both so the comparison succeeds.
const a = new Date(2024, 3, 2, 8, 15, 30, 742);
const b = new Date(2024, 3, 2, 8, 15, 30, 9);
console.log(a.getTime() === b.getTime()); // false — same second, different ms
const ta = new Date(a); ta.setSeconds(ta.getSeconds(), 0);
const tb = new Date(b); tb.setSeconds(tb.getSeconds(), 0);
console.log(ta.getTime() === tb.getTime()); // true
console.log(ta.toTimeString().slice(0, 8)); // 08:15:30Expiry from a lifetime in seconds
Adding 3600 seconds carries through minutes, hours and the date change at midnight without any manual arithmetic. Passing 0 for milliseconds in the same call keeps the expiry on a whole second.
function expiresAt(issued, seconds) {
const out = new Date(issued);
out.setSeconds(out.getSeconds() + seconds, 0);
return out;
}
const issued = new Date(2024, 8, 1, 23, 59, 30, 500);
console.log(expiresAt(issued, 3600).toTimeString().slice(0, 8)); // 00:59:30
console.log(expiresAt(issued, 3600).toDateString()); // Mon Sep 02 2024
console.log(expiresAt(issued, 45).toTimeString().slice(0, 8)); // 00:00:15
Discussion