js-public-holidays-za

A simple JavaScript utility to get South African public holidays for any date range, including observed holidays when a holiday falls on a Sunday.

Features

• Returns all South African public holidays between two dates
• Handles observed holidays (if a holiday falls on a Sunday, the following Monday is included)
• Supports both fixed-date and Easter-relative holidays
• No dependencies, pure vanilla JS

Usage

Installation

npm install js-public-holidays-za

Usage

ESM (import)

import { getSAPublicHolidaysBetween } from 'js-public-holidays-za';

const start = new Date("2025-01-01");
const end = new Date("2026-12-31");
const holidays = getSAPublicHolidaysBetween(start, end);

for (const h of holidays) {
  console.log(
    `${h.date.toLocaleDateString("en-ZA")} (${h.weekday}): ${h.name}`
  );
}

CommonJS (require)

const { getSAPublicHolidaysBetween } = require('js-public-holidays-za');

const start = new Date("2025-01-01");
const end = new Date("2026-12-31");
const holidays = getSAPublicHolidaysBetween(start, end);

for (const h of holidays) {
  console.log(
    `${h.date.toLocaleDateString("en-ZA")} (${h.weekday}): ${h.name}`
  );
}

Options

• includeObservedMondays (default: true): If true, adds an "Observed" holiday on Monday when a holiday falls on a Sunday.

API

getSAPublicHolidaysBetween(start, end, opts)

• start: Date, string, or timestamp for the start date (inclusive)
• end: Date, string, or timestamp for the end date (inclusive)
• opts: Optional object
  • includeObservedMondays: boolean (default true)
• Returns: Array of objects { date: Date, name: string, weekday: string }

How it works

• Calculates all fixed-date and Easter-relative holidays for each year in the range
• Optionally adds observed holidays for Sundays
• Returns a sorted array of holidays within the range

Module Support

This package supports both ESM (import) and CommonJS (require) usage in Node.js.

License

MIT