Handle Holidays in JavaScript With Ease – best-holiday

Best-Holiday is a compact JavaScript library for handling holidays in web applications.

It includes a set of predefined holidays (categorized into public, religious, and observance types and are associated with specific countries) and supports movable holidays like Easter Sunday, Ash Wednesday, Palm Sunday, Pentecost, Ascension Day, Mother’s Day, Father’s Day, Thanksgiving, Labor Day, Memorial Day, Veterans Day, Martin Luther King Jr. Day, Good Friday, and more.

The library provides a reliable way to access and work with holiday data. This makes it ideal for displaying relevant content, triggering special promotions, or simply acknowledging the occasion.

With six functions, Best-Holiday allows developers to retrieve, search, and customize holidays easily. Need a list of holidays for a specific day? Use getHolidaysForDay(). How about a range of dates? getHolidaysInRange() can handle that. Searching for specific holidays is a breeze with searchHolidays(). You can even calculate the date of holidays related to Easter using getEasterRelatedHoliday().

How to use it:

1. Install the package via NPM:

# NPM
$ npm install best-holiday

2. Import the required modules:

import { 
  getHolidaysForDays,
  getHolidaysInRange,
  searchHolidays,
  getEasterRelatedHoliday,
  addHoliday,
  removeHoliday
} from "balloons-js";

3. Use getHolidaysForDay() to retrieve holidays on a particular date. You can further refine the results with optional filters like ‘types’ and ‘countries’.

// getHolidaysForDay(date: Date, filters: any = {}): Holiday[]
const date = new Date(2024, 11, 25); // Dec 25, 2024
const holidays = getHolidaysForDay(date, { 
      types: ['public'],
      countries: ['US', 'UK'] 
});
console.log(holidays); // Christmas Day

4. Use getHolidaysInRange to find holidays within a specified range.

// getHolidaysInRange(startDate: Date, endDate: Date, filters = {}): { date: Date, holidays: Holiday[] }[]
const startDate = new Date(2024, 0, 1); // Jan, 2024
const endDate = new Date(2024, 11, 31); // Dec, 2024
const holidays = getHolidaysInRange(startDate, endDate, { 
      countries: ['US', 'UK'] // return an array of all holidays in 2024
});
console.log(holidays)

5. Use searchHolidays to search for holidays based on a query.

// searchHolidays(query: string, year: number, filters: any = {}): Holiday[]
const holidays = searchHolidays('Christmas', 2024, { 
      countries: 'US' 
});
console.log(holidays);

6. Use getEasterRelatedHoliday to calculate the date of a holiday based on its offset from Easter Sunday.

// getEasterRelatedHoliday(year: number, offsetDays: number = 0): Date
const goodFriday = getEasterRelatedHoliday(2024, -1);
console.log(goodFriday);

7. Add/remove custom holidays.

// add a custom holiday
addHoliday({
  name: "My Birthday",
  date: (year) => new Date(year, 10, 01), // 11/01
  country: "US",
  type: "Custom"
});
// remove a holiday
removeHoliday("Christmas Day");

Changelog:

12/23/2025

• v1.1.8