moment-holiday
Advanced tools
A Moment.js plugin for handling holidays.
npm install --save moment-holiday
var moment = require('moment-holiday');
moment().holiday('Christmas');
<script src="moment.js"></script>
<script src="moment-holiday.js"></script>
<script>
moment().isHoliday();
</script>
bower install --save moment-holiday
moment-holiday.js does not come with any locales built-in by default. However, the following files are included for your convenience:
build/moment-holiday-pkg.min.js - moment-holiday with all available locales built-in.build/moment-holiday-us.min.js - moment-holiday with the United States locale built-in.build/moment-holiday.min.js - Minified version of moment-holiday with no locales built-in.You can generate the above files by running gulp build.
You can also generate your own custom builds of moment-holiday by using gulp with the following options:
moment-holiday-custom.js)For example:
gulp --name=moment-holiday-ar.js --locale=Argentina --locale=Easter --set=Argentina --min
Sourcemaps are automatically created for all minified builds.
or holidays
Searches for holiday(s) by keywords. Returns a single moment object, an object containing moment objects with the holiday names as keys, or false if no holidays were found.
moment().holiday(holidays, adjust);
//or
moment().holidays(holidays, adjust);
moment().holiday('Memorial Day');
//moment("2017-05-29T00:00:00.000")
moment().holiday('Totally not a holiday');
//false
moment().holiday(['Dad Day']);
//{ 'Father\'s Day': moment("2017-06-18T00:00:00.000") }
moment().holidays(['Turkey Day', 'New Years Eve']);
//{ 'Thanksgiving Day': moment("2017-11-23T00:00:00.000"),
// 'New Year\'s Eve': moment("2017-12-31T00:00:00.000") }
moment().holidays(['Not actually a holiday', 'Mothers Day']);
//{ 'Mother\'s Day': moment("2017-05-14T00:00:00.000") }
moment('2018-01-01').holiday('Veterans Day');
//moment("2018-11-11T00:00:00.000")
moment('2018-01-01').holiday('Veterans Day', true);
//moment("2018-11-12T00:00:00.000")
moment().holidays();
//Returns all holidays
Returns the name of the holiday (or true if holidays parameter is used) if the given date is in fact a holiday or false if it isn't. Will return an array of holiday names if multiple holidays land on that same day.
moment().isHoliday(holidays, adjust);
true if there is a match. Can be a string to compare with a single holiday or an array for multiple. Defaults to all holidays.moment('2017-12-25').isHoliday();
//Christmas Day
moment('2005-03-15').isHoliday();
//false
moment('2009-10-31').isHoliday('Halloween');
//true
moment('2017-12-31').isHoliday();
//New Year's Eve
moment('2017-12-31').isHoliday(null, true);
//false
moment('2017-04-17').isHoliday(null, true);
//[ 'Easter Sunday', 'Easter Monday' ]
or previousHolidays
Returns an array (or a moment object if count is set to 1) containing the previous holidays before the given date.
moment().previousHoliday(count, adjust);
//or
moment().previousHolidays(count, adjust);
1.moment().previousHoliday();
//moment("2017-07-04T00:00:00.000")
moment('2001-02-14').previousHolidays(5);
//[ moment("2001-01-15T00:00:00.000"),
// moment("2001-01-01T00:00:00.000"),
// moment("2000-12-31T00:00:00.000"),
// moment("2000-12-25T00:00:00.000"),
// moment("2000-12-24T00:00:00.000") ]
moment('2001-02-14').previousHolidays(5, true);
//[ moment("2001-01-15T00:00:00.000"),
// moment("2001-01-01T00:00:00.000"),
// moment("2000-12-25T00:00:00.000"),
// moment("2000-11-24T00:00:00.000"),
// moment("2000-11-23T00:00:00.000") ]
moment().previousHoliday().isHoliday();
//Independence Day
or nextHolidays
Returns an array (or a moment object if count is set to 1) containing the next holidays after the given date.
moment().nextHoliday(count, adjust);
//or
moment().nextHolidays(count, adjust);
1.moment().nextHoliday();
//moment("2017-09-04T00:00:00.000")
moment('2010-05-23').nextHolidays(5);
//[ moment("2010-05-31T00:00:00.000"),
// moment("2010-06-20T00:00:00.000"),
// moment("2010-07-04T00:00:00.000"),
// moment("2010-09-06T00:00:00.000"),
// moment("2010-10-11T00:00:00.000") ]
moment('2010-05-23').nextHolidays(5, true);
//[ moment("2010-05-31T00:00:00.000"),
// moment("2010-06-21T00:00:00.000"),
// moment("2010-07-05T00:00:00.000"),
// moment("2010-09-06T00:00:00.000"),
// moment("2010-10-11T00:00:00.000") ]
moment().nextHoliday().isHoliday();
//Labor Day
Returns an array containing the holidays between the given date and the date parameter or false if no dates were found.
moment().holidaysBetween(date, adjust);
moment().holidaysBetween(moment().endOf('year'));
//[ moment("2017-09-04T00:00:00.000"),
// moment("2017-10-09T00:00:00.000"),
// moment("2017-10-31T00:00:00.000"),
// moment("2017-11-11T00:00:00.000"),
// moment("2017-11-23T00:00:00.000"),
// moment("2017-11-24T00:00:00.000"),
// moment("2017-12-24T00:00:00.000"),
// moment("2017-12-25T00:00:00.000") ]
moment('2011-11-01').holidaysBetween('2011-12-31');
//[ moment("2011-11-11T00:00:00.000"),
// moment("2011-11-24T00:00:00.000"),
// moment("2011-11-25T00:00:00.000"),
// moment("2011-12-24T00:00:00.000"),
// moment("2011-12-25T00:00:00.000") ]
moment('2011-11-01').holidaysBetween('2011-12-31', true);
//[ moment("2011-11-11T00:00:00.000"),
// moment("2011-11-24T00:00:00.000"),
// moment("2011-11-25T00:00:00.000"),
// moment("2011-12-23T00:00:00.000"),
// moment("2011-12-26T00:00:00.000"),
// moment("2011-12-30T00:00:00.000") ]
moment('2017-01-01').holidaysBetween();
//[ moment("2017-01-16T00:00:00.000"),
// moment("2017-02-14T00:00:00.000"),
// moment("2017-02-20T00:00:00.000"),
// moment("2017-03-17T00:00:00.000"),
// moment("2017-05-14T00:00:00.000"),
// moment("2017-05-29T00:00:00.000"),
// moment("2017-06-18T00:00:00.000"),
// moment("2017-07-04T00:00:00.000") ]
true to make all holidays that land on a Saturday go to the prior Friday and all holidays that land on a Sunday go to the following Monday. Defaults to false.Canada/AB - AlbertaCanada/BC - British ColumbiaCanada/MB - ManitobaCanada/NB - New BrunswickCanada/NL - Newfoundland and LabradorCanada/NS - Nova ScotiaCanada/NT - Northwest TerritoriesCanada/NU - NunavutCanada/ON - OntarioCanada/PE - Prince Edward IslandCanada/QC - QuebecCanada/SK - SaskatchewanGermany/BB - BrandenburgGermany/BW - Baden-WürttembergGermany/BY - BayernGermany/HE - HessenGermany/MV - Mecklenburg-VorpommernGermany/NW - Nordrhein-WestfalenGermany/RP - Rheinland-PfalzGermany/SN - SachsenGermany/SL - SaarlandGermany/ST - Sachsen-AnhaltGermany/TH - ThüringenRather than listing all of the holidays here, to see available holidays, view the source of the locale file.
Easter related holidays for any locale will only be available if the Easter locale has been added. It's automatically added if you are using Node. (You can still easily add them in even when not using Node. See: Modifying Holidays)
You can add and remove holidays by using the following helper functions:
Note: Helper functions can be chained.
Sets the holidays to be used.
moment.modifyHolidays.set(['New Years Day', 'Memorial Day', 'Thanksgiving']);
moment().holidays(); // Returns all holidays
//{ 'New Year\'s Day': moment("2017-01-01T00:00:00.000"),
// 'Memorial Day': moment("2017-05-29T00:00:00.000"),
// 'Thanksgiving Day': moment("2017-11-23T00:00:00.000") }
moment.modifyHolidays.set({
"My Birthday": {
date: '11/17',
keywords: ['my', 'birthday']
},
"Last Friday of the year": {
date: '12/(5,-1)',
keywords_y: ['friday']
}
});
moment().holidays(); // Returns all holidays
//{ 'My Birthday': moment("2017-11-17T00:00:00.000"),
// 'Last Friday of the year': moment("2017-12-29T00:00:00.000") }
Adds holiday(s) to the holidays being used.
moment.modifyHolidays.add({
"Inauguration Day": {
date: '1/20',
keywords_y: ['inauguration']
}
});
moment().holiday('Inauguration');
//moment("2017-01-20T00:00:00.000")
Removes holiday(s) from the holidays being used.
moment.modifyHolidays.remove('Christmas');
moment.modifyHolidays.remove(['Dad Day', 'Mom Day', 'Saint Paddys Day']);
Sets the holidays being used back to the way they were before they were last changed.
moment.modifyHolidays.set(['Christmas', 'Thanksgiving', 'Mothers Day', 'Fathers Day']);
moment().holidays();
//{ 'Mother\'s Day': moment("2017-05-14T00:00:00.000"),
// 'Father\'s Day': moment("2017-06-18T00:00:00.000"),
// 'Thanksgiving Day': moment("2017-11-23T00:00:00.000"),
// 'Christmas Day': moment("2017-12-25T00:00:00.000") }
moment.modifyHolidays.remove(['Thanksgiving', 'Christmas']);
moment().holidays();
//{ 'Mother\'s Day': moment("2017-05-14T00:00:00.000"),
// 'Father\'s Day': moment("2017-06-18T00:00:00.000") }
moment.modifyHolidays.undo();
moment().holidays();
//{ 'Mother\'s Day': moment("2017-05-14T00:00:00.000"),
// 'Father\'s Day': moment("2017-06-18T00:00:00.000"),
// 'Thanksgiving Day': moment("2017-11-23T00:00:00.000"),
// 'Christmas Day': moment("2017-12-25T00:00:00.000") }
Simply loads a locale file and makes it available without modifying the current holidays.
moment.modifyHolidays.load('Argentina');
moment.modifyHolidays.load(['Canada', 'Easter']);
You can also use these functions to set or add holidays from an available locale file:
moment.modifyHolidays.set('Canada').add('Easter');
moment('2001-12-26').isHoliday('Boxing Day');
//true
moment.modifyHolidays.add('Easter').remove('Good Friday');
moment().holiday(['Easter Sunday', 'Good Friday']);
//{ 'Easter Sunday': moment("2017-04-16T00:00:00.000") }
You use these same functions to specify regions to add:
moment.modifyHolidays.set('Germany/SN');
moment('2017-11-22').isHoliday();
//Buß- und Bettag
moment.modifyHolidays.set('Canada/QC/ON');
moment().holidays(['boxing', 'baptiste']);
//{ 'Boxing Day': moment("2017-12-26T00:00:00.000"),
// 'St. Jean Baptiste Day': moment("2017-06-24T00:00:00.000") }
You can also cherry-pick the holidays you want from a locale by passing a string or an array of strings as the second parameter:
moment.modifyHolidays.add('Easter', ['ascension', 'pentecost']);
moment().holiday(['ascension', 'pentecost']);
//{ 'Ascension Day': moment("2017-05-25T00:00:00.000"),
// 'Pentecost Sunday': moment("2017-06-04T00:00:00.000") }
moment.modifyHolidays.add('Germany/BB', 'Ostersonntag');
moment('2001-09-14').isHoliday();
//[ 'Easter Sunday', 'Ostersonntag' ]
Note: If you're not using Node (or anything that doesn't support the require function), you'll need to make sure that you include the locale file(s) that you're trying to use. For example:
<script src="./moment-holiday/locale/canada.js"></script>
<script src="./moment-holiday/locale/easter.js"></script>
<script>
moment.modifyHolidays.set('Canada').add('Easter');
moment('2001-12-26').isHoliday('Boxing Day');
//true
</script>
Holiday objects accept the following options:
date (Required) - The date of the holiday in the format of Month/Day. A day wrapped in parentheses () means a specific day of the week and expects two values separated by a comma ,. The first part is the day of the week as recognized by moment().day() (0=Sunday, 6=Saturday). The second part (optional) is the 1-indexed index of that day of week unless separated by brackets [] which means "The weekday on or before/after this day". Two dates separated by a vertical bar | means a date range. You may also specific a 4-digit year by adding an additional / after the day.
Examples:
5/20 - The 20th of May.7/(1,3) - The third Monday of July.3/(4,-1) - The last Thursday of March.6/(2,[16]) - The Tuesday on or after the 16th of June.11/(5,[-9]) - The Friday on or before the 9th of November.8/21|9/4 - The 21st of August through the 4th of September.11 - The 11th of every month of the year.(0) - Every Sunday of the year.(6,-2) - The second to last Friday of every month of the year.10/(3) - Every Wednesday in October.12/7/2014 - December 7th, 2014.(6)/2014 - Every Saturday of the year 2014.2/(1,1)|5/(5,-1) - The first Monday of February through the last Friday of May.4/(3,[-11])|5/(0,1) - The Wednesday on or before the 11th of March through the first Sunday of May.keywords - An array of optional keywords.
keywords_y - An array of required keywords.
keywords_n - An array of banned keywords.
regions - An array of region abbreviations that the holiday is celebrated in. Basically a white-list.
regions_n - An array of region abbreviations that the holiday is NOT celebrated in. Basically a black-list.
RegEx can be used in keywords. For example, st[\\s\\.] will match St Jean and St. Patrick, but not Christmas and x-?mas will match xmas and x-mas.
View the source of moment-holiday.js for a better look at how the keywords work.
This is a handy little function that allows you to extend the functionality of the date parser. It accepts a single function as a variable that gets passed a moment object and the date string as variables. It can return a single moment object, an array of moment objects, false to bail on parsing, or nothing at all to continue with the default parser.
Example:
moment.modifyHolidays.add({
"Friday The Thirteenth": {
date: 'fridaythethirteenth',
keywords_y: ['friday'],
keywords: ['thirteen', '13', 'the']
}
}).extendParser(function(m, date){
if (date === 'fridaythethirteenth') {
var days = [];
for (i = 0; i < 12; i++) {
var d = moment(m).month(i).date(13);
if (d.day() === 5) { days.push(moment(d)); }
}
if (!days.length) { return false; }
return days;
}
});
moment().holiday('Friday 13th');
//[ moment("2017-01-13T00:00:00.000"),
// moment("2017-10-13T00:00:00.000") ]
You can also see how we take advantage of this by viewing the source of locale/easter.js.
Locale files are simply files that add holidays and special holiday parsing functionality for other countries. They are all located in the locale/ folder.
Pull Requests will be accepted (and encouraged!) but must meet the following guidelines:
moment.holidays.[locale] object matching the filename all in lowercase (spaces are converted to underscores).
locale/japan.js would need to have moment.holidays.japan in it.local/Japan.js or moment.holidays.Japannpm test.See the source of locale/canada.js and locale/easter.js for good examples of locale files.
MIT. See the License file for more info.
[1.5.0] - 2017-08-03
modifyHolidays.load function.holiday function will now return false is the current holiday set is empty and the holiday parameter is set to null.test.js more dynamic for all locales.us locale is now United States and is no longer built-in to moment-holiday.js by default (You can still get the one with United States built-in by using build/moment-holiday-us.js).FAQs
A Moment.js plugin for handling holidays.
The npm package moment-holiday receives a total of 2,051 weekly downloads. As such, moment-holiday popularity was classified as popular.
We found that moment-holiday demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.