JavaScript Date setTime() Method

What You’ll Learn

setTime() writes the full instant on a Date using epoch milliseconds—the same number getTime() returns. This guide covers syntax, shifting by duration, copying timestamps, and comparisons with field setters.

Introduction

APIs, databases, and Date.now() give you millisecond timestamps. When you already have that number, field setters like setHours() are awkward—setTime(ms) sets the entire instant in one step.

The value is milliseconds since 1 January 1970 00:00:00 UTC (Unix epoch). Like other setters, it mutates the Date and returns the same numeric value as getTime() afterward.

Understanding the setTime() Method

Date.prototype.setTime(milliseconds) replaces every calendar and clock field at once. Local getters (getHours, getDate, etc.) reflect the new instant in your timezone; toISOString() shows the UTC representation.

To shift by a duration, add milliseconds first: date.setTime(date.getTime() + offsetMs). To copy one Date to another: target.setTime(source.getTime()).

📝 Syntax

dateObj.setTime(milliseconds)

Parameters

• milliseconds — Epoch milliseconds since 1970-01-01 UTC (same unit as getTime() and Date.now()).

Return value

• The updated epoch milliseconds (identical to date.getTime() after the call).
• NaN if the argument is NaN (Date becomes invalid).

Examples Gallery

Open DevTools Console (F12) or use Try-it links. Epoch 0 is always 1970-01-01T00:00:00.000Z in UTC.

const date = new Date();
date.setTime(0);

console.log(date.getTime());        // 0
console.log(date.toISOString());    // "1970-01-01T00:00:00.000Z"

0
1970-01-01T00:00:00.000Z

const date = new Date(2026, 2, 1, 12, 0, 0);
const oneDayMs = 24 * 60 * 60 * 1000;
date.setTime(date.getTime() + oneDayMs);

console.log(date.getDate());  // 2
console.log(date.getHours()); // 12

2
12

const source = new Date(2026, 5, 15, 10, 30, 0);
const copy = new Date(0);
copy.setTime(source.getTime());

console.log(copy.getTime() === source.getTime());  // true
console.log(copy === source);                      // false

true
false

const date = new Date(2026, 0, 1);
const returned = date.setTime(1_735_689_600_000);

console.log("Type:", typeof returned);                 // "number"
console.log("Matches getTime():", returned === date.getTime()); // true

Type: number
Matches getTime(): true

const iso = "2026-06-15T09:30:00.000Z";
const ms = Date.parse(iso);
const date = new Date();
date.setTime(ms);

console.log(date.toISOString());  // "2026-06-15T09:30:00.000Z"

const bad = Date.parse("not-a-date");
console.log(Number.isNaN(bad));   // true

2026-06-15T09:30:00.000Z
true

🚀 Common Use Cases

• API timestamps — apply server epoch ms to a Date object.
• Duration shifts — add days/hours via getTime() + offset.
• Clone instants — copy.setTime(original.getTime()).
• Reset to known instant — snap back to a saved timestamp.
• Benchmarks — store start/end ms, then setTime for replay.
• Invalid guard — skip setTime when parse returns NaN.

📝 Notes

• setTime() sets the full instant—not just the time-of-day.
• Same unit as getTime(), Date.now(), and Date.parse() results.
• For midnight local snap, use setHours(0, 0, 0, 0)—not setTime unless you compute the ms.
• Mutates the original Date—clone when preserving the old instant.
• Returns epoch ms, not the Date—no fluent chaining on the return value.
• Validate parsed values with Number.isNaN() before calling setTime.

💡 Best Practices