Durations

Moment.js also has duration objects. Where a moment is defined as single points in time, durations are defined as a length of time.

Durations do not have a defined beginning and end date. They are contextless.

A duration is conceptually more similar to '2 hours' than to 'between 2 and 4 pm today'. As such, they are not a good solution to converting between units that depend on context.

For example, a year can be defined as 366 days, 365 days, 365.25 days, 12 months, or 52 weeks. Trying to convert years to days makes no sense without context. It is much better to use moment#diff for calculating days or years between two moments than to use Durations.

Creating1.6.0+

  1. moment.duration(Number, String);
  2. moment.duration(Number);
  3. moment.duration(Object);
  4. moment.duration(String);

To create a duration, call moment.duration() with the length of time in milliseconds.

  1. moment.duration(100); // 100 milliseconds

If you want to create a moment with a unit of measurement other than milliseconds, you can pass the unit of measurement as well.

  1. moment.duration(2, 'seconds');
  2. moment.duration(2, 'minutes');
  3. moment.duration(2, 'hours');
  4. moment.duration(2, 'days');
  5. moment.duration(2, 'weeks');
  6. moment.duration(2, 'months');
  7. moment.duration(2, 'years');

The same shorthand for moment#add and moment#subtract works here as well.

KeyShorthand
yearsy
monthsM
weeksw
daysd
hoursh
minutesm
secondss
millisecondsms

Much like moment#add, you can pass an object of values if you need multiple different units of measurement.

  1. moment.duration({
  2.     seconds: 2,
  3.     minutes: 2,
  4.     hours: 2,
  5.     days: 2,
  6.     weeks: 2,
  7.     months: 2,
  8.     years: 2
  9. });

As of 2.1.0, moment supports parsing ASP.NET style time spans. The following formats are supported.

The format is an hour, minute, second string separated by colons like 23:59:59. The number of days can be prefixed with a dot separator like so 7.23:59:59. Partial seconds are supported as well 23:59:59.999.

  1. moment.duration('23:59:59');
  2. moment.duration('23:59:59.999');
  3. moment.duration('7.23:59:59.999');
  4. moment.duration('23:59'); // added in 2.3.0

As of 2.3.0, moment also supports parsing ISO 8601 durations.

  1. moment.duration('P1Y2M3DT4H5M6S');
  2. moment.duration('P1M');

As of 2.11.0, duration format strings with a space between days and restis supported.

  1. moment.duration('7 23:59:59.999');

As of 2.13.0, mixed negative and positive signs are supported when parsing durations.

  1. moment.duration('PT-6H3M')

As of 2.18.0, invalid durations are supported, similarly to invalidmoments. To create an invalid duration you can pass NaN for a value ofa unit.

In upcoming releases expect invalid durations to cover more cases (likenull values for units).

  1. moment.duration(NaN);
  2. moment.duration(NaN, 'days');
  3. moment.duration.invalid();

Clone2.19.0+

  1. moment.duration().clone();

Create a clone of a duration. Durations are mutable, just like moment objects,so this lets you get a snapshot, at some point in time.

  1. var d1 = moment.duration();
  2. var d2 = d1.clone();
  3. d1.add(1, 'second');
  4. d1.asMilliseconds() !== d2.asMilliseconds();

Humanize1.6.0+

  1. moment.duration().humanize();

Sometimes, you want all the goodness of moment#from but you don't want to have to create two moments, you just want to display a length of time.

Enter moment.duration().humanize().

  1. moment.duration(1, "minutes").humanize(); // a minute
  2. moment.duration(2, "minutes").humanize(); // 2 minutes
  3. moment.duration(24, "hours").humanize();  // a day

By default, the return string is suffixless. If you want a suffix, pass in true as seen below.

  1. moment.duration(1, "minutes").humanize(true); // in a minute

For suffixes before now, pass in a negative number.

  1. moment.duration(-1, "minutes").humanize(true); // a minute ago

Invalid durations are humanized to the localized version of Invalid Date.

  1. moment.duration.invalid().humanize(); // Invalid Date

Milliseconds1.6.0+

  1. moment.duration().milliseconds();
  2. moment.duration().asMilliseconds();

To get the number of milliseconds in a duration, use moment.duration().milliseconds().

It will return a number between 0 and 999.

  1. moment.duration(500).milliseconds(); // 500
  2. moment.duration(1500).milliseconds(); // 500
  3. moment.duration(15000).milliseconds(); // 0

If you want the length of the duration in milliseconds, use moment.duration().asMilliseconds() instead.

  1. moment.duration(500).asMilliseconds(); // 500
  2. moment.duration(1500).asMilliseconds(); // 1500
  3. moment.duration(15000).asMilliseconds(); // 15000

Seconds1.6.0+

  1. moment.duration().seconds();
  2. moment.duration().asSeconds();

To get the number of seconds in a duration, use moment.duration().seconds().

It will return a number between 0 and 59.

  1. moment.duration(500).seconds(); // 0
  2. moment.duration(1500).seconds(); // 1
  3. moment.duration(15000).seconds(); // 15

If you want the length of the duration in seconds, use moment.duration().asSeconds() instead.

  1. moment.duration(500).asSeconds(); // 0.5
  2. moment.duration(1500).asSeconds(); // 1.5
  3. moment.duration(15000).asSeconds(); // 15

Minutes1.6.0+

  1. moment.duration().minutes();
  2. moment.duration().asMinutes();

As with the other getters for durations, moment.duration().minutes() gets the minutes (0 - 59).

moment.duration().asMinutes() gets the length of the duration in minutes.

Hours1.6.0+

  1. moment.duration().hours();
  2. moment.duration().asHours();

As with the other getters for durations, moment.duration().hours() gets the hours (0 - 23).

moment.duration().asHours() gets the length of the duration in hours.

Days1.6.0+

  1. moment.duration().days();
  2. moment.duration().asDays();

As with the other getters for durations, moment.duration().days() gets the days (0 - 30).

moment.duration().asDays() gets the length of the duration in days.

Weeks1.6.0+

  1. moment.duration().weeks();
  2. moment.duration().asWeeks();

As with the other getters for durations, moment.duration().weeks() gets the weeks (0 - 4).

moment.duration().asWeeks() gets the length of the duration in weeks.

Pay attention that unlike the other getters for duration, weeks are counted as a subset of the days, and are not taken off the days count.

Note: The length of a duration in weeks is defined as 7 days.

Months1.6.0+

  1. moment.duration().months();
  2. moment.duration().asMonths();

As with the other getters for durations, moment.duration().months() gets the months (0 - 11).

moment.duration().asMonths() gets the length of the duration in months.

Years1.6.0+

  1. moment.duration().years();
  2. moment.duration().asYears();

As with the other getters for durations, moment.duration().years() gets the years.

moment.duration().asYears() gets the length of the duration in years.

Add Time2.1.0+

  1. moment.duration().add(Number, String);
  2. moment.duration().add(Number);
  3. moment.duration().add(Duration);
  4. moment.duration().add(Object);

Mutates the original duration by adding time.

The same keys and shorthands used to create durations can be used here as the second argument.

  1. var a = moment.duration(1, 'd');
  2. var b = moment.duration(2, 'd');
  3. a.add(b).days(); // 3

Note that adding an invalid duration to any other duration results in an invalidduration.

Subtract Time2.1.0+

  1. moment.duration().subtract(Number, String);
  2. moment.duration().subtract(Number);
  3. moment.duration().subtract(Duration);
  4. moment.duration().subtract(Object);

Mutates the original duration by subtracting time.

The same keys and shorthands used to create durations can be used here as the second argument.

  1. var a = moment.duration(3, 'd');
  2. var b = moment.duration(2, 'd');
  3. a.subtract(b).days(); // 1

Note that adding an invalid duration to any other duration results in an invalidduration.

Using Duration with Diff2.1.0+

  1. var duration = moment.duration(x.diff(y))

You can also use duration with moment#diff to get the duration between two moments. To do so, simply pass the moment#diff method into moment#duration as follows:

  1.   var x = new moment()
  2.   var y = new moment()
  3.   var duration = moment.duration(x.diff(y))
  4.   // returns duration object with the duration between x and y

See here for more information about moment#diff.

As Unit of Time2.1.0+

  1. moment.duration().as(String);

As an alternate to Duration#asX, you can use Duration#as('x'). All the shorthand keys from moment#add apply here as well.

  1. duration.as('hours');
  2. duration.as('minutes');
  3. duration.as('seconds');
  4. duration.as('milliseconds');

Invalid durations return NaN for all units.

Get Unit of Time2.1.0+

  1. moment.duration().get(String);

As an alternate to Duration#x() getters, you can use Duration#get('x'). All the shorthand keys from moment#add apply here as well.

  1. duration.get('hours');
  2. duration.get('minutes');
  3. duration.get('seconds');
  4. duration.get('milliseconds');

Invalid durations return NaN for all units.

As JSON2.9.0+

  1. moment.duration().toJSON();

When serializing a duration object to JSON, it will be represented as anISO8601 string.

  1. JSON.stringify({
  2.     postDuration : moment.duration(5, 'm')
  3. }); // '{"postDuration":"PT5M"}'

Invalid durations return Invalid Date as json representation.

Is a Duration1.6.0+

  1. moment.isDuration(obj);

To check if a variable is a moment duration object, use moment.isDuration().

  1. moment.isDuration() // false
  2. moment.isDuration(new Date()) // false
  3. moment.isDuration(moment()) // false
  4. moment.isDuration(moment.duration()) // true
  5. moment.isDuration(moment.duration(2, 'minutes')) // true

As ISO 8601 String2.8.0+

  1. moment.duration().toISOString();

Returns duration in string as specified by ISO 8601 standard.

  1. moment.duration(1, 'd').toISOString() // "P1D"

Format PnYnMnDTnHnMnS description:

UnitMeaning
PP stands for period. Placed at the start of the duration representation.
YYear
MMonth
DDay
TDesignator that precedes the time components.
HHour
MMinute
SSecond

Locale2.17.1+

  1. moment.duration().locale();
  2. moment.duration().locale(String);

You can get or set the locale of a duration using locale(…). The locale will affect the duration's string methods, like humanize(). See the intl section for more information on internationalization generally.

  1. moment.duration(1, "minutes").locale("en").humanize(); // a minute
  2. moment.duration(1, "minutes").locale("fr").humanize(); // une minute
  3. moment.duration(1, "minutes").locale("es").humanize(); // un minuto

Suffixes in humanize() are also internationalized:

  1. moment.duration(1, "minutes").locale("en").humanize(true); // in a minute
  2. moment.duration(1, "minutes").locale("fr").humanize(true); // dans une minute
  3. moment.duration(1, "minutes").locale("es").humanize(true); // en un minuto
  5. moment.duration(-1, "minutes").locale("en").humanize(true); // a minute ago
  6. moment.duration(-1, "minutes").locale("fr").humanize(true); // il y a une minute
  7. moment.duration(-1, "minutes").locale("es").humanize(true); // hace un minuto