JavaScript Date valueOf() Method

What You’ll Learn

valueOf() returns a Date’s instant as epoch milliseconds—the same number as getTime(). It also powers automatic numeric conversion when you subtract dates or use Number(date).

Introduction

A Date object represents one moment in time internally as milliseconds since the Unix epoch. Methods like getFullYear() expose calendar fields, but sometimes you need the raw number instead.

valueOf() is the generic “give me the primitive value” hook inherited from Object.prototype. On dates, that primitive is always the epoch millisecond timestamp. Understanding it explains why date1 - date2 just works.

Understanding the valueOf() Method

Date.prototype.valueOf() converts the instance to a number:

• Return type — primitive number (not a Date, not a string).
• Unit — milliseconds since 1970-01-01 00:00:00 UTC.
• Equivalence — identical to getTime() for valid Date objects.
• Coercion — called when JavaScript needs a numeric Date (subtraction, Number(), unary +).
• Invalid dates — returns NaN.

📝 Syntax

date.valueOf()

Parameters

• None.

Return value

• Epoch milliseconds for the date-time stored in the object.
• NaN when the Date is invalid.

Related APIs

• getTime() — explicit timestamp read (same result).
• Date.now() — current epoch ms without creating a Date.
• Date.parse() — parse a string into epoch ms.

Examples Gallery

Open DevTools Console (F12) or use Try-it links. Verify timestamps with toISOString() when helpful.

const date = new Date("2026-03-15T12:00:00.000Z");

const timestamp = date.valueOf();

console.log(timestamp);           // 1773576000000 (example engine value)
console.log(date.toISOString());  // "2026-03-15T12:00:00.000Z"

1773576000000
2026-03-15T12:00:00.000Z

const date = new Date("2026-07-17T08:00:00.000Z");

console.log(date.valueOf());
console.log(date.getTime());
console.log(date.valueOf() === date.getTime());  // true

1784275200000
1784275200000
true

const date1 = new Date("2022-01-01T00:00:00.000Z");
const date2 = new Date("2023-01-01T00:00:00.000Z");

if (date1.valueOf() < date2.valueOf()) {
  console.log("date1 is earlier than date2");
} else if (date1.valueOf() > date2.valueOf()) {
  console.log("date1 is later than date2");
} else {
  console.log("same instant");
}

date1 is earlier than date2

const date = new Date("2026-01-01T00:00:00.000Z");

console.log(Number(date));
console.log(+date);
console.log(Number(date) === date.valueOf());  // true

1767225600000
1767225600000
true

const start = new Date("2026-01-01T00:00:00.000Z");
const end = new Date("2026-07-01T00:00:00.000Z");

const diffMs = end.valueOf() - start.valueOf();
const diffDays = diffMs / (1000 * 60 * 60 * 24);

console.log(diffMs);
console.log(diffDays);  // 181

15638400000
181

🚀 Common Use Cases

• Sort events — order logs or records by valueOf().
• Deadline checks — compare Date.now() with a stored Date.
• Elapsed timing — subtract start/end timestamps after an operation.
• Serialization prep — store numeric instants in databases or JSON numbers.
• Understanding coercion — debug why date + 1 behaves differently from date - 1.
• Invalid detection — Number.isNaN(date.valueOf()) flags bad parses.

📝 Notes

• valueOf() returns milliseconds, not seconds.
• For valid dates, valueOf() === getTime() is always true.
• Invalid dates yield NaN—check before comparing or sorting.
• date + 1 converts to string first (uses toString()), not valueOf().
• date - 1 uses numeric coercion via valueOf().
• Prefer getTime() in new code when readability matters.

💡 Best Practices