Moment.js

• Home
• Documentation
• Unit Tests
• Github

Get it

• Github
• npm

Use it

• In NodeJS
• In the browser

Parsing

• Javascript Date Object
• Unix Timestamp
• String
• String + Format
• String + Formats
• Now
• Javascript Array

Manipulation

• Add
• Subtract
• Milliseconds
• Seconds
• Minutes
• Hours
• Date
• Day
• Month
• Year

Display

• Formatted date
• Time from another moment
• Time from now
• Calendar time
• Difference
• Native Date
• Value
• Milliseconds
• Seconds
• Minutes
• Hours
• Date
• Day
• Month
• Year
• Leap Year
• Timezone Offset
• Daylight Savings Time

I18N

• Changing languages
• Loading languages in NodeJS
• Loading languages in the browser
• Adding your language to Moment.js

Customization

• Month Names
• Month Abbreviations
• Weekday Names
• Weekday Abbreviations
• Long Date Formats
• Relative Time
• AM/PM
• Calendar
• Ordinal

Moment.js Documentation

A lightweight javascript date library for parsing, manipulating, and formatting dates.

Where to get it

Github

You can also clone the project with Git by running:

git clone git://github.com/timrwood/moment

npm

npm install moment

Where to use it

Moment was designed to work in both the browser and in NodeJS. All code will work in both environments. All unit tests are run in both environments.

In NodeJS

var moment = require('moment');
moment().add('hours', 1).fromNow(); // "1 hour ago"

In the browser

<script src="moment.min.js"></script>
moment().add('hours', 1).fromNow(); // "1 hour ago"

Parsing

Instead of modifying the native Date.prototype, Moment.js creates a wrapper for the Dateobject.

Note: The Moment.js prototype is exposed through moment.fn. If you want to add your own functions, that is where you would put them.

To get this wrapper object, simply call moment()with one of the supported input types.

Javascript Date Object

A native Javascript Date object.

var day = new Date(2011, 9, 16);
var dayWrapper = moment(day); 

var otherDay = moment(new Date(2020, 3, 7));

This is the fastest way to get a Moment.js wrapper.

Unix Timestamp

An integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.

var day = moment(1318781876406);

String

A string that can be parsed by Date.parse.

var day = moment("Dec 25, 1995");

Browser support for this is somewhat inconsistent. If you are not getting consistent results, you can try using String + Format.

String + Format

An input string and a format string

var day = moment("12-25-1995", "MM-DD-YYYY");

The format parsing tokens are similar to the tokens for moment.fn.format.

The parser ignores non-alphanumeric characters, so both moment("12-25-1995", "MM-DD-YYYY")and moment("12\25\1995", "MM-DD-YYYY")will return the same thing.

Unless you specify a timezone offset, parsing a string will create a date in the current timezone.

A workaround to parse a string in UTC is to append "+0000" to the end of your input string, and add "ZZ"to the end of your format string.

Important:Parsing a string with a format is by far the slowest method of creating a date. If you have the ability to change the input, it is much faster (~15x) to use Unix timestamps.

String + Formats

An input string and an array of format strings.

This is the same as String + Format, only it will try to match the input to multiple formats.

var day = moment("12-25-1995", ["MM-DD-YYYY", "YYYY-MM-DD"]);

This approach is fundamentally problematic in cases like the following, where there is a difference in big, medium, or little endian date formats.

var day = moment("05-06-1995", ["MM-DD-YYYY", "DD-MM-YYYY"]); // June 5th or May 6th?

Important:THIS IS SLOW. This should only be used as a last line of defense.

Now

To get the current date and time, just call moment()with no parameters.

var now = moment();

This is essentially the same as calling moment(new Date()).

Javascript Array

An array mirroring the parameters passed into new Date()

[year, month = 0, date = 1, hours = 0, minutes = 0, seconds = 0, milliseconds = 0] 
var day = moment([2010, 1, 14, 15, 25, 50, 125]); // February 14th, 3:25:50.125 PM

Any value past the year is optional, and will default to the lowest possible number.

var day = moment([2010]); // January 1st 
var day = moment([2010, 6]); // July 1st 
var day = moment([2010, 6, 10]); // July 10th

Construction with an array will create a date in the current timezone. To create a date from an array at UTC, you can use the following.

var array = [2010, 1, 14, 15, 25, 50, 125];
var day = moment(Date.UTC.apply({}, array));

Manipulation

Once you have a Moment.js wrapper object, you may want to manipulate it in some way. There are a number of moment.fnmethods to help with this.

All manipulation methods are chainable, so you can do crazy things like this.

moment().add('days', 7).subtract('months', 1).year(2009).hours(0).minutes(0).seconds(0);

Adding Time

This is a pretty robust function for adding time to an existing date. To add time, pass the key of what time you want to add, and the amount you want to add.

moment().add('days', 7);

There are some shorthand keys as well if you're into that whole brevity thing.

moment().add('d', 7);

If you want to add multiple different keys at the same time, you can pass them in as an object literal.

moment().add('days', 7).add('months', 1); // with chaining 
moment().add({days:7,months:1}); // with object literal

There are no upper limits for the amounts, so you can overload any of the parameters.

moment().add('milliseconds', 1000000); // a million milliseconds 
moment().add('days', 360); // 360 days

Special considerations for months and years

If the day of the month on the original date is greater than the number of days in the final month, the day of the month will change to the last day in the final month.

Example:

moment([2010, 0, 31]);                  // January 31 
moment([2010, 0, 31]).add('months', 1); // February 28

There are also special considerations to keep in mind when adding time that crosses over Daylight Savings Time.If you are adding years, months, weeks, or days, the original hour will always match the added hour.

var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
m.hours(); // 5
m.add('days', 1).hours(); // 5

If you are adding hours, minutes, seconds, or milliseconds, the assumption is that you want precision to the hour, and will result in a different hour.

var m = moment(new Date(2011, 2, 12, 5, 0, 0)); // the day before DST in the US
m.hours(); // 5
m.add('hours', 24).hours(); // 6

Subtracting Time

This is exactly the same as moment.fn.add, only instead of adding time, it subtracts time.

moment().subtract('days', 7);

Milliseconds

There are a number of shortcut getter and setter functions. Much like in jQuery, calling the function without paremeters causes it to function as a getter, and calling with a parameter causes it to function as a setter.

These map to the corresponding function on the native Dateobject.

moment().milliseconds(30) === new Date().setMilliseconds(30);
moment().milliseconds() === new Date().getMilliseconds();

Accepts numbers from 0 to 999

Seconds

Accepts numbers from 0 to 59

moment().seconds(30); // set the seconds to 30

Minutes

Accepts numbers from 0 to 59

moment().minutes(30); // set the minutes to 30

Hours

Accepts numbers from 0 to 23

moment().hours(12); // set the hours to 12

Date

Accepts numbers from 1 to 31

moment().date(5); // set the date to 5

NOTE: moment.fn.date is used to set the date of the month, and moment.fn.day is used to set the day of the week.

Day

moment().day(5); // set the day of the week to Friday

This method can be used to set the day of the week, Sunday being 0 and Saturday being 6.

moment.fn.day can also be overloaded to set to a weekday of the previous week, next week, or a week any distance from the moment.

moment().day(-7); // set to last Sunday (0 - 7) 
moment().day(7); // set to next Sunday (0 + 7)
moment().day(10); // set to next Wednesday (3 + 7)
moment().day(24); // set to 3 Wednesdays from now (3 + 7 + 7 + 7)

Month

Accepts numbers from 0 to 11

moment().month(5); // set the month to June

Year

moment().year(1984); // set the year to 1984

Display

Once parsing and manipulation are done, you need some way to display the moment. Moment.js offers many ways of doing that.

Formatted Date

The most robust display option is moment.fn.format. It takes a string of tokens and replaces them with their corresponding values from the Date object.

var date = new Date(2010, 1, 14, 15, 25, 50, 125);
moment(date).format("dddd, MMMM Do YYYY, h:mm:ss a"); // "Sunday, February 14th 2010, 3:25:50 pm"
moment(date).format("ddd, hA");                       // "Sun, 3PM"

To escape characters in format strings, you can use a backslash before any character. NOTE: if you are using a string literal, you will need to escape the backslash, hence the double backslash below.

moment().format('\\L'); // outputs 'L'

To escape multiple characters, you can wrap the characters in square brackets.

moment().format('[today] DDDD'); // 'today Sunday'

While these date formats are very similar to LDML date formats, there are a few minor differences regarding day of month, day of year, and day of week.

For a breakdown of a few different date formatting tokens, see this chart of date formatting tokens.

To compare moment.js date formatting speeds against other libraries, check out http://jsperf.com/date-formatting .

Note: Baron Schwartz wrote a pretty cool date formatter that caches formatting functions to avoid expensive regex or string splitting. It's so much faster than any of the other libraries, that it's best to compare it on its own, rather than pollute the "best of the uncompiled" formatting libs.

Here's the moment.js vs xaprb performance tests, and here is the article describing his methods.

Time from another moment

Another common way of displaying time, sometimes called timeago, is handled by moment.fn.from.

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.from(b) // "a day ago"

The first parameter is anything you can pass to moment()or a Moment.js object.

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.from(b);                     // "a day ago"
a.from([2007, 0, 28]);         // "a day ago"
a.from(new Date(2007, 0, 28)); // "a day ago"
a.from("1-28-2007");           // "a day ago"

NOTE: Because it only accepts one parameter to pass in the date info, if you need to use String + Format or String + Formats, you should create a Moment.js object first and then call moment.fn.from

var a = moment();
var b = moment("10-10-1900", "MM-DD-YYYY");
a.from(b);

If you pass trueas the second parameter, you can get the value without the suffix. This is useful wherever you need to have a human readable length of time.

var start = moment([2007, 0, 5]);
var end = moment([2007, 0, 10]);
start.from(end);       // "in 5 days"
start.from(end, true); // "5 days"

The base strings are customized by moment.langor by modifying the values directly using moment.relativeTime.

The breakdown of which string is displayed when is outlined in the table below.

Time from now

This is just a map to moment.fn.from(new Date())

moment([2007, 0, 29]).fromNow(); // 4 years ago

Like moment.fn.from, if you pass trueas the second parameter, you can get the value without the suffix.

moment([2007, 0, 29]).fromNow();     // 4 years ago
moment([2007, 0, 29]).fromNow(true); // 4 years

Calendar time

Calendar time is displays time relative to now, but slightly differently than moment.fn.from.

moment.fn.calendar will format a date with different strings depending on how close to today the date is.

These strings are localized, and can be customized with moment.calendar or moment.lang.

Difference

To get the difference in milliseconds, use moment.fn.diff like you would use moment.fn.from.

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.diff(b) // 86400000

To get the difference in another unit of measurement, pass that measurement as the second argument.

var a = moment([2007, 0, 29]);
var b = moment([2007, 0, 28]);
a.diff(b, 'days') // 1

The supported measurements are "years", "months", "weeks", "days", "hours", "minutes", and "seconds"

By default, moment.fn.diffwill return a rounded number. If you want the floating point number, pass trueas the third argument.

var a = moment([2007, 0]);
var b = moment([2008, 5]);
a.diff(b, 'years')       // 1
a.diff(b, 'years', true) // 1.5

Native Date

To get the native Date object that Moment.js wraps, use moment.fn.native.

moment([2007, 0, 29]).native(); // returns native Date object

Value

moment.fn.valueOfsimply outputs the unix timestamp.

moment(1318874398806).valueOf(); // 1318874398806

Milliseconds

These are the getters mentioned in the Manipulationsection above.

These map to the corresponding function on the native Dateobject.

moment().milliseconds() === new Date().getMilliseconds();

moment().milliseconds(); // get the milliseconds (0 - 999)

Seconds

moment().minutes(); // get the seconds (0 - 59)

Minutes

moment().minutes(); // get the minutes (0 - 59)

Hours

moment().hours(); // get the hours (0 - 23)

Date

moment().date(); // get the date of the month (1 - 31)

Day

moment().day(); // get the day of the week (0 - 6)

Month

moment().month(); // get the month (0 - 11)

Year

moment().year(); // get the four digit year

Leap Year

moment.fn.isLeapYearreturns true if that year is a leap year, and false if it is not.

moment([2000]).isLeapYear() // true
moment([2001]).isLeapYear() // false
moment([2100]).isLeapYear() // false

Timezone Offset

moment().zone(); // get the timezone offset in minutes (60, 120, 240, etc.)

Daylight Savings Time

moment.fn.isDST checks if the current moment is in daylight savings time or not.

moment([2011, 2, 12]).isDST(); // false, March 12 2011 is not DST
moment([2011, 2, 14]).isDST(); // true, March 14 2011 is DST

I18N

Moment.js has pretty robust support for internationalization. You can load multiple languages onto the same instance and easily switch between them.

Changing languages

By default, Moment.js comes with English language strings. If you need other languages, you can load them into Moment.js for later use.

To load a language, pass the key and the string values to moment.lang.

Note: More details on each of the parts of the language bundle can be found in the customization section.

moment.lang('fr', {
    months : "Janvier_Février_Mars_Avril_Mai_Juin_Juillet_Aout_Septembre_Octobre_Novembre_Décembre".split("_"),
    monthsShort : "Jan_Fev_Mar_Avr_Mai_Juin_Juil_Aou_Sep_Oct_Nov_Dec".split("_"),
    weekdays : "Dimanche_Lundi_Mardi_Mercredi_Jeudi_Vendredi_Samedi".split("_"),
    weekdaysShort : "Dim_Lun_Mar_Mer_Jeu_Ven_Sam".split("_"),
    longDateFormat : { 
        L : "DD/MM/YYYY",
        LL : "D MMMM YYYY",
        LLL : "D MMMM YYYY HH:mm",
        LLLL : "dddd, D MMMM YYYY HH:mm"
    },
    meridiem : {
        AM : 'AM',
        am : 'am',
        PM : 'PM',
        pm : 'pm'
    },
    calendar : {
        sameDay: "[Ajourd'hui à] LT",
        nextDay: '[Demain à] LT',
        nextWeek: 'dddd [à] LT',
        lastDay: '[Hier à] LT',
        lastWeek: 'dddd [denier à] LT',
        sameElse: 'L'
    },
    relativeTime : {
        future : "in %s",
        past : "il y a %s",
        s : "secondes",
        m : "une minute",
        mm : "%d minutes",
        h : "une heure",
        hh : "%d heures",
        d : "un jour",
        dd : "%d jours",
        M : "un mois",
        MM : "%d mois",
        y : "une année",
        yy : "%d années"
    },
    ordinal : function (number) {
        return (~~ (number % 100 / 10) === 1) ? 'er' : 'ème';
    }
});

Once you load a language, it becomes the active language. To change active languages, simply call moment.langwith the key of a loaded language.

moment.lang('fr');
moment(1316116057189).fromNow() // il y a une heure
moment.lang('en');
moment(1316116057189).fromNow() // an hour ago

Loading languages in NodeJS

Loading languages in NodeJS is super easy. If there is a language file in moment/lang/named after that key, the first call to moment.langwill load it.

var moment = require('moment');
moment.lang('fr');
moment(1316116057189).fromNow(); // il y a une heure

Right now, there is only support for English, French, Italian, and Portuguese. If you want your language supported, create a pull request or send me an email with the required files.

Loading languages in the browser

Loading languages in the browser just requires you to include the language files.

<script src="moment.min.js"></script>
<script src="lang/fr.js"></script>
<script src="lang/pt.js"></script>

There are minified versions of each of these languages. There is also a minified version of all of the languages bundled together.

<script src="moment.min.js"></script><script src="lang/all.min.js"></script>

Ideally, you would bundle all the files you need into one file to minimize http requests.

<script src="moment-fr-it.min.js"></script>

Adding your language to Moment.js

To add your language to Moment.js, submit a pull request with both a language file and a test file. You can find examples in moment/lang/fr.jsand moment/test/lang/fr.js

To run the tests, do node build.

If there are no errors building, then do node testor open moment/test/index.html.

If all the tests pass, submit that pull request, and thank you for contributing!

Customization

If you don't need i18n support, you can manually override the customization values. However, any calls to moment.langwill override them. It is probably safer to create a language for your specific customizations than to override these values manually.

Month Names

moment.monthsshould be an array of the month names.

moment.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];

Month Abbreviations

moment.monthsShortshould be an array of the month abbreviations.

moment.monthsShort = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

Weekday Names

moment.weekdaysshould be an array of the weekdays names.

moment.weekdays = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];

Weekday Abbreviations

moment.weekdaysShortshould be an array of the weekdays abbreviations.

moment.weekdaysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];

Long Date Formats

moment.longDateFormatshould be an object containing a key/value pair for each long date format (L, LL, LLL, LLLL).

moment.longDateFormat = { 
    L: "MM/DD/YYYY",
    LL: "MMMM D YYYY",
    LLL: "MMMM D YYYY h:mm A",
    LLLL: "dddd, MMMM D YYYY h:mm A"
};

Relative Time

moment.relativeTime should be an object of the replacement strings for moment.fn.from.

moment.relativeTime = {
    future: "in %s",
    past: "%s ago",
    s: "seconds",
    m: "a minute",
    mm: "%d minutes",
    h: "an hour",
    hh: "%d hours",
    d: "a day",
    dd: "%d days",
    M: "a month",
    MM: "%d months",
    y: "a year",
    yy: "%d years"
};

future refers to the prefix/suffix for future dates, and past refers to the prefix/suffix for past dates. For all others, a single character refers to the singular, and an double character refers to the plural.

If a language requires additional processing for a token, It can set the token as a function with the following signature. The function should return a string.

function(number, withoutSuffix, key) {
    return string;
}

The key variable refers to the replacement key in the relativeTime object. (eg. 's', 'm', 'mm', 'h', etc.)

The number variable refers to the number of units for that key. For 'm', the number is the number of minutes, etc.

The withoutSuffix variable will be true if the token will be displayed without a suffix, and false if it will be displayed with a suffix. (The reason for the inverted logic is because the default behavior is to display with the suffix.)

AM/PM

moment.meridiem should be a map of upper and lowercase versions of am/pm.

moment.meridiem = {
    am : 'am',
    AM : 'AM',
    pm : 'pm',
    PM : 'PM'
};

Calendar

moment.calendar should have the following formatting strings.

moment.meridiem = {
    lastDay : '[Yesterday at] LT',
    sameDay : '[Today at] LT',
    nextDay : '[Tomorrow at] LT',
    lastWeek : '[last] dddd [at] LT',
    nextWeek : 'dddd [at] LT',
    sameElse : 'L'
};

Ordinal

moment.ordinal should be a function that returns the ordinal for a given number.

moment.ordinal = function (number) {
    var b = number % 10;
    return (~~ (number % 100 / 10) === 1) ? 'th' : 
        (b === 1) ? 'st' : 
        (b === 2) ? 'nd' : 
        (b === 3) ? 'rd' : 'th';
};

For more information on ordinal numbers, see wikipedia