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
• Seconds
• Minutes
• Hours
• Date
• Month
• Year

Display

• Formatted date
• Time from another moment
• Time from now
• Difference
• Native Date
• Value
• Seconds
• Minutes
• Hours
• Date
• Day
• Month
• Year
• Leap Year

I18N

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

I18N

• Month Names
• Month Abbreviations
• Weekday Names
• Weekday Abbreviations
• Long Date Formats
• Relative Time
• AM/PM
• 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
995", "MM-DD-YYYY")will return the same thing.

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.

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 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 Date.UTC()

[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

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

Subtracting Time

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

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

Seconds

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().seconds(30) === new Date().setSeconds(30);
moment().seconds() === new Date().getSeconds();

Minutes

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

Hours

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

Date

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

Month

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"

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

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

Seconds

These are the getters mentioned in the Manipulationsection above.

These map to the corresponding function on the native Dateobject.

moment().seconds() === new Date().getSeconds();

Minutes

moment().minutes(); // get the minutes

Hours

moment().hours(); // get the hours

Date

moment().date(); // get the date (0 - 31)

Day

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

Month

moment().month(); // get the month

Year

moment().year(); // get the 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

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"
    },
    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'
};

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