indian-festivals

Production-quality, open-source TypeScript library for calculating dates of major Indian festivals, national days, religious events, and famous regional observances across current and future years (2026, 2027, 2030, 2050+).

Disclaimer: This package provides festival and important-day dates for cultural and developer use. It is not an official government holiday calendar database.

Features

• 🇮🇳 Comprehensive Coverage: National days, major Hindu, Sikh, Islamic, Christian, Buddhist, and Jain festivals, and famous regional observances.
• 🔮 Future-Year Computation: Algorithmic calculation engines (fixed Gregorian rules, Meeus Easter algorithm, Tabular Hijri conversion, Lunisolar approximations) compute dates for any year (2026, 2027, 2030, 2050+).
• 🏷 Clean Taxonomy: Events categorized under 'national', 'religious', 'cultural', 'regional', or 'commemorative' with tradition tags (Hindu, Sikh, Islamic, Christian, Secular, etc.).
• 🗺 Regional Filtering: Support for India national events (IN) and state-specific regional festivals (PB, KL, TN, WB, MH, AS, BR, etc.).
• 🌙 Islamic Moon Sighting Flag: Islamic events automatically carry requiresConfirmation: true to indicate dependency on local crescent moon sightings.
• ⚡️ Offline & Zero Dependencies: 100% self-contained, no external API network calls.
• 📦 Dual ESM + CommonJS: Ships with CJS, ESM, and TypeScript .d.ts declaration files.

Installation

npm install indian-festivals

Or using Yarn / pnpm:

yarn add indian-festivals
# or
pnpm add indian-festivals

Quick Start

import { IndianFestivals } from 'indian-festivals';

// Initialize calendar instance
const calendar = new IndianFestivals();

// 1. Fetch all festivals for 2026
const festivals2026 = calendar.getFestivals(2026);
console.log(festivals2026);

// 2. Fetch festivals for a future year (e.g. 2030)
const festivals2030 = calendar.getFestivals(2030);
console.log(festivals2030);

// 3. Filter festivals for a specific region (e.g. Punjab 'PB' or Kerala 'KL')
const pbFestivals = calendar.getFestivalsByRegion('PB', 2026);

// 4. Check events occurring on a specific date
const events = calendar.isFestival('2026-01-26');
console.log(events[0].name); // "Republic Day"

// 5. Get next upcoming festival
const next = calendar.getNextFestival('2026-01-01');
console.log(next?.name, 'on', next?.date);

API Reference

new IndianFestivals(options?: IndianFestivalsOptions)

interface IndianFestivalsOptions {
  region?: string; // Optional default region code e.g. "PB", "KL", "IN"
}

calendar.getFestivals(year: number): FestivalEvent[]

Returns array of all applicable FestivalEvent objects for the target year, sorted chronologically by date.

const festivals = calendar.getFestivals(2026);

calendar.getFestival(id: string, year: number): FestivalEvent | null

Retrieves a single festival by its stable ID (e.g. 'diwali', 'republic_day', 'lohri') for a given year.

const diwali = calendar.getFestival('diwali', 2026);
console.log(diwali?.date); // "2026-11-08"

calendar.getFestivalsByDate(date: string | Date): FestivalEvent[]

Returns an array of FestivalEvent objects occurring on the specified YYYY-MM-DD string or JavaScript Date.

const events = calendar.getFestivalsByDate('2026-08-15');

calendar.isFestival(date: string | Date): FestivalEvent[]

Alias for getFestivalsByDate. Returns matching event objects or [] if none.

calendar.getFestivalsByRegion(regionCode: string, year: number): FestivalEvent[]

Returns festivals celebrated in the specified state/UT code (includes national IN events + region-specific events).

const punjabFestivals = calendar.getFestivalsByRegion('PB', 2026);

calendar.getFestivalsByCategory(category: FestivalCategory, year: number): FestivalEvent[]

Filters events by category ('national', 'religious', 'cultural', 'regional', 'commemorative').

const nationalDays = calendar.getFestivalsByCategory('national', 2026);

calendar.getNextFestival(date: string | Date): FestivalEvent | null

Finds the earliest upcoming festival after the target date.

calendar.getPreviousFestival(date: string | Date): FestivalEvent | null

Finds the latest festival prior to the target date.

IndianFestivals.getRegions(): Record<string, string>

Returns static dictionary of supported ISO region codes to human-readable names.

Festival Categories & Data Model

Every event is returned as a FestivalEvent:

interface FestivalEvent {
  id: string;                    // Stable identifier e.g. "diwali"
  name: string;                  // Display name
  alternateNames?: string[];     // Synonyms e.g. ["Deepavali"]
  date: string;                  // YYYY-MM-DD
  category: FestivalCategory;    // 'national' | 'religious' | 'cultural' | 'regional' | 'commemorative'
  tradition?: Tradition;         // 'Hindu' | 'Sikh' | 'Islamic' | 'Christian' | 'Secular' | etc.
  regions: string[];             // Applicable region codes e.g. ["IN"] or ["PB", "HR"]
  description?: string;          // Cultural overview
  dateSource: DateSource;        // 'fixed' | 'calculated' | 'verified'
  verified?: boolean;            // Verified status
  requiresConfirmation?: boolean;// Moon-sighting dependency flag
}

Islamic Moon-Sighting Caveat

[!NOTE] Dates for Islamic observances (such as Eid al-Fitr, Eid al-Adha, Ramadan, Muharram, and Milad-un-Nabi) are calculated using astronomical Tabular Islamic Calendar algorithms. Each Islamic event returns requiresConfirmation: true to inform applications that official observation depends on local crescent moon sightings.

License

MIT License © 2026