Moment.js is a legacy project, now in maintenance mode. In most cases, you should choose a different library.
See some alternatives at the end of this post.

Proceed at your own peril

Moment.js is a mutable wrapper with a fluent interface for the native JavaScript date object (property _d). Use .toDate() to convert back to a JavaScript date.

Dates are interpreted as local time. Unless instantiated with moment.utc().

const now = moment(); // current local time
const a = moment('2016-01-05');
const b = a.clone().add(1, 'week');
b.format('YYYY-MM-DD HH:mm:ss');

moment/moment : Parse, validate, manipulate, and display dates in javascript.

Install

Give yourself a moment

npm install moment

Parse

Many Moment functions accept a moment-like argument. Where moment-like is Moment | String | Number | Date | Array | Object.

Another date

moment(Date) and moment(Moment) == moment().clone()

An array

moment([year, month, day, hour, minute, second, ms]). Only year is required. Mirrors date so month is zero indexed. moment().toArray() returns this format.

An object

moment({year: 2010, month: 3, ...}) or just moment({y: 1, M: 0, d: 1, h: 0, m: 0, s: 0, ms: 0}). Can provide year, years or y. Accepts numbers or strings. date is an additional alias for day. Note a capital M for months and lowercase m for minutes. moment().toObject() returns an object with plural key names (and date).

A number / Unix timestamp

• moment(milliseconds).
• moment.unix(seconds).utc(). Without .utc() will create a local date.

Partials

moment('15', 'hh') == today 15:00:00.000

Parse strings

moment(str) accepts ISO 8601 dates. If you’re not using an ISO 8601 date string, provide the format and turn off forgiving mode by passing true as the third argument. Otherwise fallback to new Date(str) which has varying browser support.

// Forgiving mode (default)
moment('01-01-2016', 'MM/DD/YYYY', false).format();
// --> 2016-01-01T00:00:00-06:00

// Strict mode
moment('01-01-2016', 'MM/DD/YYYY', true).format();
// --> Invalid date

// Forgiving is very forgiving
moment('2016 is a date', 'YYYY-MM-DD').isValid();
// --> true because 2016 was matched

• Also accepts an array for allowing multiple formats. First exact hit matches. Docs mention multiple formats is considerably slower.
• Third parameter true means strict mode. Otherwise forgiving mode.
• Third parameter could also be the locale ex fr. The fourth parameter is then the mode.

ISO 8601 formats

More exotic ISO 8601 formats:

• 2019-W10: Week
• 2019-W10-7: Date with week number
• --03-10: Date without year
• 2019-069: Ordinal date

Parse Docs

Common formats

Dates

Times

Locale aware

Other

Display

• toISOString(): Example: 2019-04-19T11:57:15.094Z. Aliases: toJSON() and JSON.stringify(moment()).
• toISOString(keepOffset = false): Passing keepOffset = true: 2019-04-19T13:57:15.094+02:00. Alias: format()
• valueOf() or +moment(): Unix Timestamp (ms). Like Date.valueOf().
• .unix(): Unix Timestamp (s).

format Docs

format

Accepts a string parameter like “Parse strings” but with some additional options

• [literal]
• Mo: 1st -> 12th month
• Qo: 1st quarter
• DDDo: 1st -> 365th day

fromNow Docs

fromNow

moment().fromNow(); // a few seconds ago
moment().fromNow(true); // a few seconds

There is also:

• moment().from([, Boolean])
• moment().toNow()
• moment().to(moment-like[, Boolean])
• moment.duration(1, 'minutes').humanize(): “a minute”
• moment().calendar(): Last/Next Monday, Yesterday, Today, Tomorrow or else DD/MM/YYYY.

Query

All these methods return a Boolean.

moment.isMoment(m);
moment.isDate(new Date());

const m = moment();
m.isValid();

moment.max(moment(), moment(), ...);
moment.min([moment(), moment()]);

m.isBefore(moment-like = moment(), String = 'milliseconds');
// .isAfter()
// .isSame(), .isSameOrBefore(), .isSameOrAfter()

m.isBetween(moment-like, moment-like, String = 'milliseconds', String = '()');

Last parameter of isBetween:

• (): Both exclusive (default)
• []: Both inclusive
• [): First inclusive, second exclusive

Difference

const m = moment();

m.diff(moment-like = moment(), String = 'milliseconds', Boolean = false);
// --> Negative result: m is earlier than first argument. Think "m - argument < 0"

m.diff(moment(), 'days');
// --> in days, truncated
m.diff(moment(), 'days', true);
// --> result as floating point

Duration Docs

Diff as a Duration

const duration = moment.duration(m.diff(m));
duration.milliseconds(); // amount of milliseconds in the duration
duration.asMilliseconds(); // entire duration in milliseconds

Manipulate Docs

Mutate

const m = moment();
m.add(Number, 'days'); // or just 'd'
m.add(moment.duration());
m.add({days: 1, M: 1});
// Also: .subtract()

m.startOf('day'); // year, second, isoWeek, quarter, ...
// Also: .endOf()

Get + Set

Overloaded getters/setters jQuery style. Both singular and plural names exist. Setters mutate the Moment object. Prefer singular names because plural names tend to get deprecated. 😃 (So far: years, months and dates are deprecated)

const m = moment();

// getters
m.second();

// setters
m.second(0);

// for:
// .milliseconds() .seconds() .minutes() .hours()
// .year() .month() .date()
// .dayOfYear() .quarter()

// .day(Number | String) // day of the week with 0=Sunday and 6=Saturday
// .weekday(Number) // day of the week, locale aware
// .isoWeekday(Number | String) // day of the week with 1=Monday and 7=Sunday
// .weekYear() and .isoWeekYear()
// .week() and .isoWeek() // week of year

// Getters only
// .weeksInYear() and .isoWeeksInYear()
// .daysInMonth()
// .isLeapYear()
// .isDST() // Is Daylight Saving Time

// Chaining: order is important
m.year(1).month(0).date(1);


// get
m.get('minute'); // Also 'minutes' and 'm'
m.get('months'); // Also 'month' and 'M'

// set
m.set('unit', 1);
m.set({years: 1, M: 2, date: 3}); // 'day' doesn't work here!

Locales

i18n Docs

By default en is loaded.

require('moment/locale/fr'); // Averages 3-5kb per locale

// All loaded locales as String[]
moment.locales();

// New default locale for all newly created moments
moment.locale('fr');

// Getter/Setter jQuery style
moment().locale('en');

Or customize yourself

Special calendars

• Jalaali Calendar
• Hijri Calendar
• Islamic Civil Calendar
• Taiwan Calendar

Timezones

moment();     // --> 2019-04-19T17:16:28+02:00
moment.utc(); // --> 2019-04-19T15:16:28Z
moment.utc() == moment().utc()
moment.utc().local() == moment()

moment().utcOffset(); // 120 (in minutes)

// Converted to local timezone
moment('2019-04-19T20:16:28+05:00');
// --> 2019-04-19T17:16:28+02:00

// Keep timezone from input
moment.parseZone('2019-04-19T20:16:28+05:00');
// --> 2019-04-19T20:16:28+05:00

Setting utcOffset

moment().utcOffset(String | Number, Boolean);

• First parameter
  • Strings -00:00, +0000 and Z
  • -16 to 16: A number of hours
  • 16- or 16+: A number of minutes
  • Any ISO8601 formatted string
• Second parameter
  • false (default): Keep the same Universal Time, change the local time.
  • true: Keep the same local time, change the Universal Time.

Plugins

rotaready/moment-range : Fancy date ranges for Moment.js

icambron/twix.js : A date range plugin for moment.js

c-trimm/moment-recur : A momentjs plugin for matching and generating recurring dates.

jsmreese/moment-duration-format : Format function plugin for the Moment Duration object.

jmeas/moment-business : Utilities for Western workweeks (addWeekDays, isWeekDay, isWeekendDay etc)

Alternatives

If your date needs are few, a few helper methods can save you the Moment (50kb) dependency. There is a reason Date is not covered in JavaScript: The Good Parts though.

You Don’t Need Moment

you-dont-need/You-Dont-Need-Momentjs : List of functions which you can use to replace moment.js + ESLint Plugin

Replace Moment with a smaller project

moment/moment : This one :)

moment/luxon : A library for working with dates and times in JS (7kb)

date-fns/date-fns : ⌛ Modern JavaScript date utility library ⌛ (13kb). Functional and tree shakeable!

iamkun/dayjs : ⏰ Immutable date library alternative to Moment.js with the same modern API (2kb)

hustcc/timeago.js : A tiny library used to format date with *** time ago statement. eg: ‘3 hours ago’. No dependency & localization & tiny. (2kb)

Steven Levithan

JavaScript Date Format at his “Flagrant Badassery” blog adds a Date.prototype.format function. (2kb)

felixge/node-dateformat : A node.js package for Steven Levithan’s excellent dateFormat() function.

Sticking with Date

const pad = value => ('0' + value).slice(-2);
const format = d => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
// --> 2019-04-14 04:14:00

Debugging

• moment().invalid(obj): Create an ‘Invalid date’.
  • moment().parsingFlags(): Get details when !isValid().
  • moment().invalidAt(): number: 0=years, 1=months, …, 6=milliseconds.
• moment().inspect(): string == moment("2019-04-19T14:12:35.694").
• moment().creationData() == {input: string, format: string, locale: Locale, isUTC: boolean, strict: boolean}.
• moment.locale('x-pseudo')