Date & time

One number, many clocks

People think about dates in many ways: birthdays, deadlines, calendars, and time zones. A JavaScript Date is much simpler. Inside, it keeps just one number.

That number is called a timestamp. It counts milliseconds (thousandths of a second) from one fixed moment: midnight at the start of January 1, 1970, in UTC. You will see that moment written as 1970-01-01T00:00:00.000Z.

UTC stands for Coordinated Universal Time. It is the world's reference clock. It never moves for summer time. Every other time zone is described as a number of hours ahead of UTC or behind it.

Everything else a Date can do is a way to read that one number, change it, or write it as text.

This lesson uses ideas from earlier lessons:

• A timestamp is a plain number.
• JSON.stringify turns a Date into text, and JSON.parse can turn that text back into a Date. You saw both in the JSON lesson.
• +date turns a Date into its timestamp. That uses object to primitive conversion.
• < and > work on dates because dates can turn into numbers, as in the Comparisons lesson.

Date.now() gives you the timestamp for right now. It is a plain number, not a Date object.

"Right now" is different for every reader. So the playground below works it out in your browser, after the page has loaded. It shows the same moment in several ways. The results marked in your time zone use your computer's clock settings.

1const now = Date.now();2const instant = new Date(now);3instant.toISOString();4instant.toString();5instant.toLocaleString();6instant.toLocaleString("en-US", { timeZone: "Asia/Tokyo" });

Here is what the playground code does:

• new Date(now) puts the timestamp inside a Date object.
• toISOString() writes the moment as text in UTC.
• toString() and toLocaleString() write the moment using your computer's time zone and language settings.
• The last line passes a language, "en-US", and a timeZone. So it shows Tokyo time in US English on every computer.

When you need the same output on every computer, choose the language and the time zone yourself. Both toLocaleString and Intl.DateTimeFormat accept them as options.

JavaScript also has a second clock. The code below uses both clocks.

1const savedAt = Date.now();2const expiresAt = savedAt + 5000;3console.log(expiresAt - savedAt);4 5const started = performance.now();6const finished = started + 500;7console.log(finished > started);

• Lines 1 to 3 use Date.now(). It tells you when something happened, like the time on a wall clock. Use it for times you save, such as "this link expires at …". Line 2 adds 5000 milliseconds (5 seconds), so line 3 prints 5000.
• Lines 5 to 7 use performance.now(). It counts milliseconds since this page opened. Use it to measure how long a task took. Line 6 adds 500, so line 7 prints true.

The example adds fixed numbers so its output is always the same. In real code, you read the clock once before the work and once after it, then subtract.

Now step through a small program. It makes a timestamp, puts it in a Date, and then reads it back in three ways.

1const stamp = Date.UTC(2024, 0, 31, 12, 0, 0);Run2const moment = new Date(stamp);3const month = moment.getUTCMonth();4const iso = moment.toISOString();5const number = +moment;

There are four common ways to create a Date:

• new Date() for the moment right now.
• new Date(timestamp) when you already have the milliseconds.
• new Date(Date.UTC(...)) when you have a year, a month, a day, and so on, and want them read as UTC. The result is the same on every computer.
• new Date("...") with an ISO string, for dates you saved as text.

An ISO string is date text in one standard shape, like "2024-03-10T09:00Z": the year, month, and day, then a T, then the time. The next section explains each part.

Each row of the table shows one way to create a Date. Read across: the code, what you get, and what to watch for.

Parsing means reading text, like "2024-03-10", and turning it into a Date. Parsing is where Date causes the most trouble. The rules for ISO strings are written down in the JavaScript standard. Other shapes, like "March 10, 2024" or "10/03/2024", have no fixed rules. Each browser may read them its own way.

Try the lab. Click each string. See whether it becomes a UTC time, a local time, a time with an offset, or an invalid date.

1new Date("2024-03-10");          // date-only ISO: UTC2new Date("2024-03-10T09:00");    // no offset: local time3new Date("2024-03-10T09:00Z");   // Z: UTC4new Date("2024-03-10T09:00+05:30");5new Date("March 10, 2024");      // non-ISO: avoid for data6new Date("not a date").getTime(); // NaN

The next example puts a date-only string next to a string with a date and a time.

1const dateOnly = new Date("2024-03-10");2const meeting = new Date("2024-03-10T09:00");3const localComponents = new Date(2024, 2, 10, 9);4console.log(dateOnly.toISOString());5console.log(meeting.getTime() === localComponents.getTime());

1. Line 1 has a date only. A date-only ISO string means midnight UTC.
2. Line 2 has a date and a time, but no Z and no offset. So it means 9:00 in your time zone.
3. Line 3 builds 9:00 on March 10 from numbers. Numbers passed to new Date are also read in your time zone. Month 2 is March.
4. Line 4 prints 2024-03-10T00:00:00.000Z on every computer.
5. Line 5 prints true on every computer. Lines 2 and 3 mean the same local moment, so their timestamps match.

The code doesn't print meeting.toISOString(). That UTC text would be different in each time zone.

ISO 8601 is the name of the standard for date text like 2024-03-10T09:00:00.000Z. Read it from left to right:

• 2024-03-10 is the year, the month, and the day.
• T separates the date from the time.
• 09:00:00.000 is hours, minutes, seconds, and milliseconds.
• Z means the time is in UTC.

Instead of Z, a string can end with an offset, like +05:30. It means "this clock time, in a place 5 hours and 30 minutes ahead of UTC". India uses that offset. A Z or an offset makes the string name one exact moment.

Date.UTC(year, monthIndex, day, hour) builds a timestamp from parts and reads them as UTC. The result is the same on every computer. Remember two things:

• The month is an index that starts at 0. January is 0 and December is 11.
• It gives back a number. Wrap it in new Date(...) when you want Date methods.

Here, a getter is a method that reads one part of a date, like the year or the hour. Dates have two sets of getters:

• Local getters read the date in your time zone: getFullYear(), getMonth(), getDate() (the day of the month), getDay() (the day of the week, with Sunday as 0), and getHours().
• UTC getters read the date in UTC: getUTCFullYear(), getUTCMonth(), and so on.

Use the UTC getters in tests. Their results don't depend on the computer's time zone.

1const jan31 = new Date(Date.UTC(2024, 0, 31, 9));2console.log(jan31.getUTCMonth()); // 0, January3console.log(jan31.getUTCDate());  // 31

Line 1 makes January 31, 2024, at 9:00 UTC. Line 2 prints 0, the month index for January. Line 3 prints 31, the day of the month.

A setter is a method that changes one part, like setMonth() or setUTCDate(). A setter changes the Date object itself. It doesn't make a new one.

Setters also overflow: if the day you ask for doesn't exist, the extra days carry over into the next month. Ask for February 31 and you get a day in March. Sometimes that helps. Sometimes it is a bug.

Step through the code below and watch one Date change.

1const due = new Date(Date.UTC(2024, 0, 31, 9));Run2due.setUTCMonth(due.getUTCMonth() + 1);3due.setUTCDate(due.getUTCDate() + 7);4console.log(due.toISOString());

1const original = new Date(Date.UTC(2024, 0, 31));2const copy = new Date(original.getTime());3copy.setUTCDate(copy.getUTCDate() + 1);4console.log(original.toISOString());5console.log(copy.toISOString());

1. Line 1 makes January 31, 2024, at midnight UTC.
2. Line 2 makes a new Date from the original's timestamp. It is a separate object, not a second name for the same one.
3. Line 3 adds one day to the copy only.
4. Line 4 prints January 31 for the original.
5. Line 5 prints February 1 for the copy.

Doing math with dates

To find the time between two exact moments, subtract one Date from the other. The result is in milliseconds. Divide it by 86_400_000, the number of milliseconds in 24 hours, to get days.

That works well for UTC times, like the moment a login expires. It doesn't always match calendar days in your own time zone. Many places move their clocks for summer time (this is called daylight saving time). On those days, a local day is 23 or 25 hours long.

1const a = new Date("2024-06-01T00:00:00Z");2const b = new Date("2024-06-01T00:00:00Z");3console.log(a === b);4console.log(a.getTime() === b.getTime());5console.log(a < new Date("2024-06-02T00:00:00Z"));

1. Line 1 makes a Date for June 1, 2024, at midnight UTC.
2. Line 2 makes a second Date for the same moment.
3. Line 3 prints false. === checks whether a and b are the very same object. They are two separate objects.
4. Line 4 prints true. getTime() gives each timestamp, and the two numbers are equal.
5. Line 5 prints true. < turns both dates into timestamps, and June 1 comes before June 2.

So when you mean "the same moment", compare timestamps with getTime() or +date. To measure a time span, you subtract those same timestamps.

You can also move a date forward with UTC setters. This is the same code you stepped through earlier.

1const due = new Date(Date.UTC(2024, 0, 31, 9));2due.setUTCMonth(due.getUTCMonth() + 1);3due.setUTCDate(due.getUTCDate() + 7);4console.log(due.toISOString());

Line 2 adds one month, and line 3 adds seven days. Line 4 prints 2024-03-09T09:00:00.000Z on every computer, because every step uses UTC.

Turning dates into text

Write dates one way for computers and another way for people:

• toISOString() is for saving and sending data. It always uses UTC and always ends with Z.
• toJSON() calls toISOString(). That is why JSON.stringify turns a Date into an ISO string.
• toLocaleString(), toLocaleDateString(), and Intl.DateTimeFormat are for people. They write the date in a person's language and style.

1const instant = new Date("2024-12-24T18:30:00Z");2console.log(instant.toISOString());3console.log(instant.toJSON());4console.log(new Intl.DateTimeFormat("en-GB", {5  weekday: "long",6  day: "numeric",7  month: "long",8  year: "numeric",9  timeZone: "UTC"10}).format(instant));11console.log(instant.toLocaleDateString("en-GB", { timeZone: "UTC" }));

1. Line 1 makes a Date for December 24, 2024, at 18:30 UTC.
2. Lines 2 and 3 print the same ISO text: 2024-12-24T18:30:00.000Z.
3. Lines 4 to 10 make a formatter with Intl.DateTimeFormat. "en-GB" means British English. The options ask for the weekday and the month as words, and for UTC. It prints Tuesday, 24 December 2024.
4. Line 11 uses toLocaleDateString with British English and UTC. It prints 24/12/2024 on every computer.

For pages people read, choose the language and the options on purpose. en-GB puts the day first, and en-US puts the month first. The Internationalization with Intl lesson covers formatting dates, numbers, lists, and plurals in depth.

Where you'll use this

Dates show up in forms, dashboards, calendars, logs, and data from APIs. They also decide when saved data is too old to use. A good habit has four steps:

1. Save the moment as an ISO string.
2. Turn it back into a Date when you need Date methods.
3. Do math with timestamps or UTC methods.
4. Turn it into text for people only at the end, when you show it.

For calendar dates, named time zones, and lengths of time, move on to Temporal instead of writing more helper code around Date.

Each row of the table is a common job. Read across to see a good first choice and why.

Common mistakes with dates

Each row of the table is one problem. Read across to see what surprises people and a safer habit.

Key takeaways

• A Date holds one timestamp in milliseconds. Its methods choose how to read it.
• Date.now() and Date.UTC() give back numbers. new Date(...) gives back an object.
• Months start at 0 when you pass numbers to new Date, Date.UTC, and setters.
• A date-only ISO string is UTC. A string with a date and a time but no offset is local time.
• For results that are the same on every computer, use UTC methods and pass a timeZone.
• toISOString() is for computers. Intl.DateTimeFormat and the toLocale methods are for people.

Up next: Temporal, newer date tools that fix many of Date's problems.