Date.parse()
Convert a date string into a timestamp in milliseconds since the epoch.
Date.parse(dateString)- Added in JavaScript ES1
Parameters
| Parameter | Type | Description |
|---|---|---|
$dateString | string | A string in the date time string format. Non-string values are converted to a string first. |
Return value
numberA number: the timestamp in milliseconds since 1 January 1970 UTC that the string represents, or NaN if the string cannot be recognised as a date.
Errors
Never throws — an unrecognised string returns NaN rather than raising an error.
Changelog
- PHP ES5The ISO 8601 date time string format became a required input format, so "2019-01-01T00:00:00.000Z" parses identically in every conforming engine.
- PHP ES2015A date-time string with no timezone offset is interpreted as local time; ES5 read it as UTC. A date-only string such as "2019-01-01" is still UTC.
- PHP ES2018Engines are required to parse back the output of toString() and toUTCString(), making those two formats safe to round-trip.
Date.parse() is the engine behind new Date(string); both run the same algorithm, one returning a number and the other an object. Reach for Date.parse() when you want the timestamp directly, or when you want to test whether a string is a date at all.
The three formats you can trust
- The ISO 8601 date time string format, which is what
toISOString()produces. - The output of
Date.prototype.toString(). - The output of
Date.prototype.toUTCString().
Everything else is implementation defined. "1970/01/01", "04 December 1995" and "01-02-03" parse in some engines, return NaN in others, and have been known to change between browser versions. The specification explicitly declines to define them, which is why the advice is to keep them out of production code.
The offset rule that catches everyone
A date-only string is read as UTC. Add a time and drop the offset — "2019-01-01T00:00:00" — and it becomes local time. The two differ by your UTC offset, which is how a birthday renders a day early for users west of Greenwich. Append Z or an explicit +hh:mm whenever the moment matters.
Example
When to use it
- Turn an API's ISO 8601 timestamp string into a number for sorting or comparison
- Validate that user-supplied text is a recognisable date before storing it
- Compute the difference between two dates given as strings without allocating objects
- Normalise timestamps from mixed sources into epoch milliseconds
Frequently asked questions
Why does Date.parse() return NaN for my date string?
Because the format is not one of the three the specification requires — ISO 8601, toString() output, or toUTCString() output — and this engine does not recognise it. Convert the string to ISO 8601 form, or split it and use Date.UTC() with the individual components.
Is Date.parse("03/15/2024") safe to use?
No. Slash-separated formats are implementation defined: V8 accepts them as US month/day/year, other engines may return NaN or read them as day/month/year. Reformat to "2024-03-15" before parsing.
What is the difference between Date.parse() and new Date(string)?
They run exactly the same parsing algorithm; Date.parse() returns a number and new Date() returns a Date object wrapping that number. Use Date.parse() when you only need the timestamp or want to test validity.
More examples
Validating a date string
Number.isNaN is the only reliable test: comparing with === NaN is always false, which is why validation written that way silently accepts every bad string.
function isValidDate(text) {
return !Number.isNaN(Date.parse(text));
}
console.log(isValidDate("2024-02-29T10:00:00Z")); // leap day exists
console.log(isValidDate(""));
console.log(isValidDate("tomorrow"));
// NaN never equals itself, so === will not work here
console.log(Date.parse("bad") === NaN);
console.log(Number.isNaN(Date.parse("bad")));Date-only versus date-time
The first two are identical because a date-only string is UTC. The third differs by exactly your timezone offset in minutes — zero only if you are running in UTC.
const dateOnly = Date.parse("2019-01-01"); // read as UTC
const withZ = Date.parse("2019-01-01T00:00:00Z");
const noOffset = Date.parse("2019-01-01T00:00:00"); // read as local
console.log(dateOnly === withZ);
console.log((noOffset - withZ) / 60000); // your UTC offset, in minutes
console.log(noOffset === withZ);Sorting records by a string timestamp
Parsing to numbers gives the comparator plain subtraction. The last line reports 160 minutes between the first and last event.
const events = [
{ name: "deploy", at: "2024-03-15T09:30:00Z" },
{ name: "rollback", at: "2024-03-15T09:05:00Z" },
{ name: "alert", at: "2024-03-15T11:45:00Z" },
];
events.sort((a, b) => Date.parse(a.at) - Date.parse(b.at));
console.log(events.map((e) => e.name));
console.log((Date.parse(events[2].at) - Date.parse(events[0].at)) / 60000);
Discussion