nz-holidays

A lightweight, zero-dependency library for New Zealand public holidays.

Installation

npm install nz-holidays

Quick Start

import { isHoliday, getHolidays, getNextHoliday } from 'nz-holidays';

// Check if today is a holiday
const today = new Date();
console.log(isHoliday(today)); // true/false

// Get all holidays for 2024
const holidays2024 = getHolidays(2024);
console.log(holidays2024);

// Get the next upcoming holiday
const nextHoliday = getNextHoliday();
console.log(`Next holiday: ${nextHoliday.name} on ${nextHoliday.date}`);

API Reference

getHolidays(year, options?)

Returns all holidays for a given year.

const holidays = getHolidays(2024, {
  includeObserved: true,  // Include observed dates for weekend holidays
  region: 'auckland'      // Include regional holidays
});

Options:

• includeObserved: Include observed dates when holidays fall on weekends (default: true)
• region: Include regional anniversary days:
  • 'auckland' - Auckland Anniversary Day
  • 'wellington' - Wellington Anniversary Day
  • 'canterbury' - Canterbury Anniversary Day
  • 'otago' - Otago Anniversary Day
  • 'southland' - Southland Anniversary Day
  • 'westland' - Westland Anniversary Day
  • 'nelson' - Nelson Anniversary Day
  • 'marlborough' - Marlborough Anniversary Day
  • 'taranaki' - Taranaki Anniversary Day
  • 'hawkes-bay' - Hawke's Bay Anniversary Day
  • 'south-canterbury' - South Canterbury Anniversary Day
  • 'chatham-islands' - Chatham Islands Anniversary Day

isHoliday(date: Date, options?: HolidayOptions): boolean

Check if a specific date is a holiday.

const christmas = new Date(2024, 11, 25);
console.log(isHoliday(christmas)); // true

// Include regional holidays
console.log(isHoliday(date, { region: 'auckland' }));

getNextHoliday(from?: Date, options?: HolidayOptions): Holiday | null

Get the next upcoming holiday from a given date (defaults to today).

const next = getNextHoliday();
const nextFromDate = getNextHoliday(new Date(2024, 6, 1));

isBusinessDay(date: Date, options?: HolidayOptions): boolean

Check if a date is a business day (not weekend or holiday).

const monday = new Date(2024, 5, 17);
console.log(isBusinessDay(monday)); // true (if not a holiday)

countBusinessDays(start: Date, end, options?): number

Count the number of business days between two dates exclusive

const start = new Date()
const end = new Date(2025, 11, 25);
console.log(countBusinessDays(start, end)); // how long til xmas?

Supported Holidays

National Holidays

• New Year's Day (1 January)
• Day after New Year's Day (2 January)
• Waitangi Day (6 February)
• Good Friday (Easter-based)
• Easter Monday (Easter-based)
• ANZAC Day (25 April)
• Matariki (Mid-winter, became holiday in 2022)
• King's Birthday (First Monday in June) *
• Labour Day (Fourth Monday in October)
• Christmas Day (25 December)
• Boxing Day (26 December)

*Called "Queen's Birthday" before 2023

Regional Holidays (Anniversary Days)

• Auckland - Monday closest to 29 January
• Wellington - Monday closest to 22 January
• Canterbury - Second Friday after first Tuesday in November
• Otago - Monday closest to 23 March
• Southland - Easter Tuesday (day after Easter Monday)
• Westland - Monday closest to 1 December
• Nelson - Monday closest to 1 February
• Marlborough - First Monday after Labour Day
• Taranaki - Second Monday in March
• Hawke's Bay - Friday before Labour Day
• South Canterbury - Fourth Monday in September
• Chatham Islands - Monday closest to 30 November

Note: Each region observes only their own anniversary day plus the national holidays.

Features

Mondayisation

When holidays fall on weekends, they're automatically "mondayised" (observed on Monday) according to NZ law.

Special Case - Consecutive Holidays: When Christmas Day and Boxing Day (or New Year's Day and Day After New Year's Day) both fall on weekends:

• If the first holiday moves to Monday, the second holiday moves to Tuesday
• This prevents both holidays from being observed on the same day

Example: Christmas 2022 (Sunday) → observed Monday, Boxing Day 2022 (Monday) → observed Tuesday

TypeScript Support

Full TypeScript definitions included:

interface Holiday {
  name: string;
  date: Date;
  type: 'national' | 'regional';
  observed?: Date;
}

interface HolidayOptions {
  includeObserved?: boolean;
  region?: 'auckland' 
  | 'wellington' 
  | 'canterbury' 
  | 'otago' 
  | 'southland' 
  | 'westland' 
  | 'nelson' 
  | 'marlborough' 
  | 'taranaki' 
  | 'hawkes-bay' 
  | 'south-canterbury' 
  | 'chatham-islands';
}