A lightweight javascript date library for parsing, manipulating, and formatting dates.
It doesn't modify the native Date.prototype so it's safe to drop into any project.
Development Version (1.0.0) 16k Source + Comments
Production Version (1.0.0) 2.2k Minified + Gzipped.
You can also clone the project with Git by running:
$ git clone git://github.com/timrwood/moment
npm install moment
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.
var moment = require('moment');
moment().add('hours', 1).fromNow(); // "1 hour ago"
<script src="moment.min.js"></script>
moment().add('hours', 1).fromNow(); // "1 hour ago"
Instead of modifying the native Date.prototype, Moment.js creates a wrapper for the Date object.
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
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.
An integer value representing the number of milliseconds since 1 January 1970 00:00:00 UTC.
var day = moment(1318781876406);
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
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.
| Input | Output |
|---|---|
| M or MM | Month |
| D or DD | Day of month |
| DDD or DDDD | Day of year |
| YY | 2 digit year (if greater than 70, will return 1900's, else 2000's) |
| YYYY | 4 digit year |
| a or A | AM/PM |
| H, HH, h, or hh | 24 hour (for 12 hour time, use in conjunction with a or A) |
| m or mm | Minutes |
| s or ss | Seconds |
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.
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.
To get the current time, just call moment() with no parameters.
var now = moment();
This is essentially the same as calling moment(new Date()).
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
Once you have a Moment.js wrapper object, you may want to manipulate it in some way. There are a number of moment.fn methods 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);
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);
| Key | Shorthand |
|---|---|
| years | y |
| months | M |
| days | d |
| hours | h |
| minutes | m |
| seconds | s |
| milliseconds | ms |
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
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
This is exactly the same as moment.fn.add, only instead of adding time, it subtracts time.
moment().subtract('days', 7);
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 Date object.
moment().seconds(30) === new Date().setSeconds(30); moment().seconds() === new Date().getSeconds();
moment().minutes(30); // set the minutes to 30
moment().hours(12); // set the hours to 12
moment().day(5); // set the day to 5
moment().month(5); // set the month to June
moment().year(1984); // set the year to 1984
Once parsing and manipulation are done, you need some way to display the moment. Moment.js offers many ways of doing that.
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"
| Token | Output |
|---|---|
| Month | |
| M | 1 2 ... 11 12 |
| Mo | 1st 2nd ... 11th 12th |
| MM | 01 02 ... 11 12 |
| MMM | Jan Feb ... Nov Dec |
| MMMM | January February ... November December |
| Day of Month | |
| D | 1 2 ... 30 30 |
| Do | 1st 2nd ... 30th 31st |
| DD | 01 02 ... 30 31 |
| Day of Year | |
| DDD | 1 2 ... 364 365 |
| DDDo | 1st 2nd ... 364th 365th |
| DDDD | 001 002 ... 364 365 |
| Day of Week | |
| d | 0 1 ... 5 6 |
| do | 0th 1st ... 5th 6th |
| ddd | Sun Mon ... Fri Sat |
| dddd | Sunday Monday ... Friday Saturday |
| Week of Year | |
| w | 1 2 ... 52 53 |
| wo | 1st 2nd ... 52nd 53rd |
| ww | 01 02 ... 52 53 |
| Year | |
| YY | 70 71 ... 29 30 |
| YYYY | 1970 1971 ... 2029 2030 |
| AM/PM | |
| A | AM PM |
| a | am pm |
| Hour | |
| H | 0 1 ... 22 23 |
| HH | 00 01 ... 22 23 |
| h | 1 2 ... 11 12 |
| hh | 01 02 ... 11 12 |
| Minute | |
| m | 0 1 ... 58 59 |
| mm | 00 01 ... 58 59 |
| Second | |
| s | 0 1 ... 58 59 |
| ss | 00 01 ... 58 59 |
| Timezone | |
| z | EST CST ... MST PST |
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 true as 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.lang or by modifying the values directly using moment.relativeTime.
The breakdown of which string is displayed when is outlined in the table below.
| Range | Key | Sample Output |
|---|---|---|
| 0 to 45 seconds | s | seconds ago |
| 45 to 90 seconds | m | a minute ago |
| 90 seconds to 45 minutes | mm | 2 minutes ago ... 45 minutes ago |
| 45 to 90 minutes | h | an hour ago |
| 90 minutes to 22 hours | hh | 2 hours ago ... 22 hours ago |
| 22 to 36 hours | d | a day ago |
| 36 hours to 25 days | dd | 2 days ago ... 25 days ago |
| 25 to 45 days | M | a month ago |
| 45 to 345 days | MM | 2 months ago ... 11 months ago |
| 345 to 547 days (1.5 years) | y | a year ago |
| 548 days+ | yy | 2 years ago ... 20 years ago |
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 true as 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
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 native Date object that Moment.js wraps, use moment.fn.native.
moment([2007, 0, 29]).native(); // returns native Date object
moment.fn.valueOf simply outputs the unix timestamp.
moment(1318874398806).valueOf(); // 1318874398806
These are the getters mentioned in the Manipulation section above.
These map to the corresponding function on the native Date object.
moment().seconds() === new Date().getSeconds();
moment().minutes(); // get the minutes
moment().hours(); // get the hours
moment().day(); // get the day
moment().month(); // get the month
moment().year(); // get the year
moment.fn.isLeapYear returns 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
Moment.js has pretty robust support for internationalization. You can load multiple languages onto the same instance and easily switch between them.
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("_"),
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.lang with 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 is super easy. If there is a language file in moment/lang/ named after that key, the first call to moment.lang will 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 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>
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.js and moment/test/lang/fr.js
To run the tests, do node build.
If there are no errors building, then do node test or open moment/test/index.html.
If all the tests pass, submit that pull request, and thank you for contributing!
If you don't need i18n support, you can manually override the customization values. However, any calls to moment.lang will override them. It is probably safer to create a language for your specific customizations than to override these values manually.
moment.months should be an array of the month names.
moment.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
moment.monthsShort should be an array of the month abbreviations.
moment.monthsShort = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
moment.weekdays should be an array of the weekdays names.
moment.weekdays = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
moment.weekdaysShort should be an array of the weekdays abbreviations.
moment.weekdaysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
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.
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