How to Add Hours to a Date Object in JavaScript

The Date object in JavaScript is used to work with dates and times. By default, when you create a new Date object, it gets initialized to the current date and time according to the system clock.

However, there are often situations when you need to add or subtract hours from a given Date object to get a new target date and time. In this comprehensive guide, you‘ll learn different methods to add hours to a JavaScript Date object.

Overview of the JavaScript Date Object

Before jumping into the methods for adding hours, let‘s first go over some basics of the built-in JavaScript Date object.

The Date object represents a single moment in time. It stores the date and time with millisecond precision. Under the hood, the Date object stores the number of milliseconds that have elapsed since midnight January 1, 1970 UTC. This is known as Unix Time or POSIX Time.

Here‘s an example of creating a new Date object to represent the current moment:

const now = new Date();

You can also initialize a Date to a specific date and time:

const moonLanding = new Date(‘July 20, 69 00:20:18‘);

The Date object provides several getter and setter methods to work with the individual units of date and time:

• getFullYear(): Get the 4-digit year
• getMonth(): Get the month number (0-indexed)
• getDate(): Get the day of month
• getHours(): Get the hour (0-23)
• getMinutes(): Get the minutes (0-59)
• getSeconds(): Get the seconds (0-59)
• getMilliseconds(): Get the milliseconds (0-999)

On the flip side, there are counterpart setter methods as well:

• setFullYear()
• setMonth()
• setDate()
• setHours()
• setMinutes()
• setSeconds()
• setMilliseconds()

Now that you understand the basics of the Date API in JavaScript, let‘s move on to the methods for adding and subtracting hours.

Method #1: Utilize getTime() and setTime()

One approach for adding and subtracting hours from a Date object is to utilize the getTime() and setTime() methods.

The getTime() method returns the number of milliseconds elapsed between January 1, 1970 00:00:00 UTC and the given date. This number is also known as the Unix timestamp.

Once you have the timestamp, you can simply add or subtract milliseconds to calculate the new target date and time.

For example, to add 5 hours:

const ONE_HOUR = 1000 * 60 * 60; // milliseconds in 1 hour

const now = new Date(); 

// Get timestamp
const timestamp = now.getTime();  

// Add 5 hours worth of milliseconds
const newTimestamp = timestamp + (5 * ONE_HOUR);  

// Update Date object  
now.setTime(newTimestamp); 

Here is an explanation of what‘s happening:

1. Get the total milliseconds from the date using getTime()
2. There are 3600000 milliseconds in 1 hour (1000 60 60)
3. Add 5 hours worth of milliseconds to the timestamp
4. Update the Date object with the new timestamp using setTime()

To make this easier, we can wrap the logic in a simple addHours() function:

function addHours(date, hours) {
  const ONE_HOUR = 1000 * 60 * 60;

  const timestamp = date.getTime();

  const newTimestamp = timestamp + (hours * ONE_HOUR);

  date.setTime(newTimestamp);

  return date; 
}

const now = new Date();

addHours(now, 5); // Adds 5 hours

This utilizes the timestamp to add any number of hours easily.

The benefit of this technique is it handles daylight saving time (DST) and any other timezone changes automatically.

One minor downside is the code requires a bit of timestamp calculation code. But overall, it provides complete date/time management.

Method #2: Manipulate Hours Directly

Another approach is to directly get and update the hour unit of the Date object using getHours() and setHours():

function addHours(date, hours) {

  const updatedHours = date.getHours() + hours;

  date.setHours(updatedHours);

  return date;

}

const now = new Date();

addHours(now, 5); // Adds 5 hours

Here we retrieve the current hours using getHours(), add the number of hours to increment, then set the updated hours with setHours().

This works great for simple hour arithmetic.

However, one major downside is it does not handle daylight saving time properly.

For example, if adding hours causes the clock to shift from standard time to DST, it will be off by an hour.

So while this method is terse, using the timestamp approach is safer for production code.

Method #3: Utilize Third-Party Libraries

Working directly with native JavaScript Dates can be verbose and tricky to handle edge cases around DST, leap years, timezone changes, etc.

There are several excellent third-party date manipulation libraries that can simplify the code. For example:

Moment.js

Moment.js is a very popular library for parsing, manipulating, and formatting dates.

To add hours using Moment, you can use add():

const now = moment(); 

now.add(5, ‘hours‘); // Adds 5 hours

Moment handles complex cases like daylight saving time for you automatically.

date-fns

The date-fns library provides over 200 functions for manipulating dates in a functional programming style:

import { addHours } from ‘date-fns‘;

const now = new Date();

addHours(now, 5); 

It has excellent documentation, lightweight code, and no dependencies. Another great option for simplifying JavaScript dates.

Luxon

Luxon is a powerful library for working with dates, times, datetimes, intervals, and durations.

Some key benefits over Moment.js include:

• Tree-shakable imports
• Immutable objects
• Summable Durations

To add hours with Luxon:

import { DateTime } from ‘luxon‘;

const now = DateTime.now();

now.plus({ hours: 5 }); 

So in summary, instead of using the native Date API directly, libraries like Moment, date-fns, and Luxon provide cleaner abstractions over common date and time operations.

Handling Daylight Saving Time Properly

One complexity when adding hours to JavaScript dates is properly accounting for Daylight Saving Time (DST) transitions.

During DST transition, an hour is typically either lost or gained relative to standard time.

For example, in the spring clocks spring forward an hour (1 AM becomes 2 AM). So there‘s a missing hour during the transition.

And in the fall, clocks fall back an hour (2 AM becomes 1 AM again) resulting in an overlapping hour.

This can cause logical bugs when doing JavaScript date math if not handled correctly.

In the first technique earlier using getTime()/setTime(), daylight saving is handled automatically for you.

But in the direct getHours()/setHours() technique, you‘ll need extra logic to detect DST transitions and handle the offset properly yourself.

Here is some sample code to add DST handling:

function addHours(date, hours) {

  // Save current date details
  const currentDate = date.getDate();  
  const currentHours = date.getHours();

  date.setHours(date.getHours() + hours);

  // Date has changed, so must have crossed DST
  if (date.getDate() !== currentDate) {

    // If hours went back, it‘s fall DST change
    if (date.getHours() < currentHours) {
      date.setHours(date.getHours() + 1);
    } else {
      // Spring DST change
      date.setHours(date.getHours() - 1); 
    }

  }

  return date;

}

This detects if the day changed during the hour increment. If so, it checks if hours went backwards (fall DST) or forwards (spring DST) and adjusts accordingly.

So properly handling DST requires significant additional logic when manipulating hours directly. This demonstrates another benefit of using the timestamp technique or date libraries.

Adding Hours to Date Object in UTC

At times, you may want to add hours in UTC/GMT rather than local timezone.

The simplest way is to convert the date to UTC first using toUTCString():

function addHoursUTC(date, hours) {

  // Convert to UTC timezone first
  date = new Date(date.toUTCString());

  // Now add hours  
  date.setHours(date.getHours() + hours);

  return date;

}

const now = new Date();

addHoursUTC(now, 5); // Adds 5 UTC hours 

This sets the Date instance to UTC, adds the hours, then returns the updated Date object.

Alternatively, you could utilize the techniques from earlier for operating directly on timestamps in UTC rather than local timezone.

But toUTCString() provides a quick way to move a date into the UTC timezone for manipulations.

Other Useful Methods for Adding Time

In addition to adding and subtracting hours, there are some other helpful methods for advancing JavaScript dates:

Adding Days

To increment dates by days, you can combine getDate() and setDate():

function addDays(date, days) {
  const currentDate = date.getDate();

  date.setDate(currentDate + days); 

  return date;
} 

This advances the day while keeping the time portion intact.

Adding Minutes

Adding increments of minutes can utilize getMinutes() and setMinutes():

function addMinutes(date, minutes) {
  const currentMins = date.getMinutes();

  date.setMinutes(currentMins + minutes);

  return date;  
}

Common Issues with Date Manipulation in JavaScript

When adding hours or otherwise manipulating Date objects in JavaScript, there are some common issues that can arise:

• Daylight saving time: As discussed earlier, failing to handle DST transitions can cause your date math to be off.

• Mutable Dates: Dates are mutable in JavaScript, so code that changes a date can cause unintended side effects elsewhere. Defensive coding with date copying is advised.

• Timezone: By default, the Date object instance represents local system timezone. So be careful when moving dates between timezones.

• Leap Years: Remember that increments across February 29 during a leap year require special handling in some cases.

• Precision: There are often fractions of a millisecond that can cause equality comparisons between date objects to fail unexpectedly. For equality checks use math deltas or libraries instead of strict equality.

So while native JavaScript Dates are enormously useful, they do contain some common footguns to avoid as well!

Conclusion

In this guide you learned a variety of techniques for adding hours to Date objects in JavaScript, including:

• Using getTime() and setTime() for flexible timestamp arithmetic
• Manipulating hours directly with getHours() and setHours()
• Leveraging third-party date libraries like Moment.js for cleaner abstractions
• Properly handling daylight saving time transitions
• Adding hours in UTC/GMT timezone
• Other useful methods like addDays() and addMinutes()

Hopefully this gives you some helpful options for incrementing date objects by hours in your JavaScript programming!