indian-festivals 🪔

A comprehensive TypeScript database of Indian festivals — covering Hindu, Islamic, Christian, Sikh, Jain, Buddhist, National, and Tribal festivals with 35+ utility functions for filtering, searching, and date-based lookups.

Created by @kuntalojha as part of the India Data Ecosystem — a suite of npm packages for developers building India-focused applications.

🪔 Overview

The indian-festivals package provides a structured, developer-friendly database of 80+ Indian festivals with rich metadata — dates from 2025 to 2030, geographic coverage by state, calendar information (Hindu & Islamic), customs, foods, rituals, and much more.

Whether you're building a tourism platform, a travel planner, a cultural app, or just need Indian festival data — this package has you covered.

📦 Installation

npm install indian-festivals

| Package Manager | Command | |-----------------|--------------------------------| | npm | npm install indian-festivals | | Yarn | yarn add indian-festivals | | PNPM | pnpm add indian-festivals | | BUN | bun add indian-festivals |

✨ Features

| Feature | Description | |---------|-------------| | 📅 70+ Festivals | Comprehensive data across 8 categories | | 🕉️ Multi-Religious | Hindu, Islamic, Christian, Sikh, Buddhist, Jain, Tribal & National | | 📖 Rich Information | Description, history, significance, customs & traditional foods | | 📆 Verified Dates | Year-wise dates from 2025 to 2030 | | 🆔 FID System | Universal Festival ID — FIDH05, supports bulk lookup | | 🗓️ Hindu Calendar | Tithi, Paksha, and Month information | | 🌙 Islamic Calendar | Day and Month in Islamic calendar | | 🔍 Powerful Search | Search with relevance score — ranked results | | 📦 TypeScript | Full type definitions included | | ⚡ Dual Module | ESM & CommonJS support | | 🪶 Zero Dependencies | Lightweight with no external dependencies |

🆔 Festival Reference — Code, FID & Name

Every festival has two identifiers:

| Identifier | Format | Example | Usage | |------------|----------|----------|------------------------------| | Code | H05 | H05 | Internal short reference | | FID | FIDx00 | FIDH05 | Public universal reference |

FID = FID prefix + Code. So FIDH05 → strips FID → H05 → Diwali. FID is case-insensitive: FIDH05, fidh05, FidH05 all work. FIDH05 is recommended.

🕉️ Hindu Festivals

| Code | Festival | FID | Public Holiday | |------|---------------------|---------|----------------| | H01 | Akshaya Tritiya | FIDH01 | ❌ | | H02 | Bhai Dooj | FIDH02 | ❌ | | H03 | Chhath Puja | FIDH03 | ❌ | | H04 | Dhanteras | FIDH04 | ❌ | | H05 | Diwali | FIDH05 | ✅ | | H06 | Durga Puja | FIDH06 | ✅ | | H07 | Dussehra | FIDH07 | ✅ | | H08 | Ganesh Chaturthi | FIDH08 | ✅ | | H09 | Govardhan Puja | FIDH09 | ❌ | | H10 | Gudi Padwa | FIDH10 | ❌ | | H11 | Hanuman Jayanti | FIDH11 | ✅ | | H12 | Holi | FIDH12 | ✅ | | H13 | Janmashtami | FIDH13 | ✅ | | H14 | Kali Puja | FIDH14 | ❌ | | H15 | Karwa Chauth | FIDH15 | ❌ | | H16 | Maha Shivaratri | FIDH16 | ✅ | | H17 | Makar Sankranti | FIDH17 | ✅ | | H18 | Nag Panchami | FIDH18 | ❌ | | H19 | Navratri | FIDH19 | ❌ | | H20 | Onam | FIDH20 | ✅ | | H21 | Poila Boishakh | FIDH21 | ❌ | | H22 | Pongal | FIDH22 | ✅ | | H23 | Raksha Bandhan | FIDH23 | ✅ | | H24 | Rama Navami | FIDH24 | ✅ | | H25 | Rath Yatra | FIDH25 | ❌ | | H26 | Saraswati Puja | FIDH26 | ❌ | | H27 | Teej | FIDH27 | ❌ | | H28 | Vasant Panchami | FIDH28 | ❌ |

☪️ Islamic Festivals

| Code | Festival | FID | Public Holiday | |------|---------------|---------|----------------| | M01 | Eid ul Adha | FIDM01 | ✅ | | M02 | Eid ul Fitr | FIDM02 | ✅ | | M03 | Milad un Nabi | FIDM03 | ✅ | | M04 | Muharram | FIDM04 | ✅ | | M05 | Shab-e-Barat | FIDM05 | ❌ |

✝️ Christian Festivals

| Code | Festival | FID | Public Holiday | |------|--------------------------|---------|----------------| | C01 | All Saints Day | FIDC01 | ❌ | | C02 | Christmas | FIDC02 | ✅ | | C03 | Easter | FIDC03 | ❌ | | C04 | Good Friday | FIDC04 | ✅ | | C05 | St. Francis Xavier Feast | FIDC05 | ❌ |

🪯 Sikh Festivals

| Code | Festival | FID | Public Holiday | |------|---------------------------|---------|----------------| | S01 | Baisakhi | FIDS01 | ✅ | | S02 | Bandi Chhor Divas | FIDS02 | ❌ | | S03 | Guru Gobind Singh Jayanti | FIDS03 | ✅ | | S04 | Guru Nanak Jayanti | FIDS04 | ✅ | | S05 | Hola Mohalla | FIDS05 | ❌ | | S06 | Lohri | FIDS06 | ❌ |

🔱 Jain Festivals

| Code | Festival | FID | Public Holiday | |------|----------------------|---------|----------------| | J01 | Jain Akshaya Tritiya | FIDJ01 | ❌ | | J02 | Jain Diwali | FIDJ02 | ❌ | | J03 | Mahavir Jayanti | FIDJ03 | ✅ | | J04 | Paryushana | FIDJ04 | ❌ | | J05 | Samvatsari | FIDJ05 | ❌ |

☸️ Buddhist Festivals

| Code | Festival | FID | Public Holiday | |------|----------------------------|---------|----------------| | B01 | Buddha Purnima | FIDB01 | ✅ | | B02 | Dhammachakra Pravartan Din | FIDB02 | ❌ | | B03 | Hemis Festival | FIDB03 | ❌ | | B04 | Losar | FIDB04 | ❌ |

🇮🇳 National Festivals & Holidays

| Code | Festival | FID | Public Holiday | |------|---------------------------|---------|----------------| | N01 | Ambedkar Jayanti | FIDN01 | ✅ | | N02 | Children's Day | FIDN02 | ❌ | | N03 | Constitution Day | FIDN03 | ❌ | | N04 | Gandhi Jayanti | FIDN04 | ✅ | | N05 | Independence Day | FIDN05 | ✅ | | N06 | International Day of Yoga | FIDN06 | ❌ | | N07 | National Unity Day | FIDN07 | ❌ | | N08 | National Youth Day | FIDN08 | ❌ | | N09 | Republic Day | FIDN09 | ✅ | | N10 | Teachers' Day | FIDN10 | ❌ |

🌿 Tribal Festivals

| Code | Festival | FID | Public Holiday | |------|-------------------|---------|----------------| | T01 | Ambubachi Mela | FIDT01 | ❌ | | T02 | Bihu | FIDT02 | ✅ | | T03 | Hornbill Festival | FIDT03 | ❌ | | T04 | Karam Festival | FIDT04 | ❌ | | T05 | Me-Dam-Me-Phi | FIDT05 | ❌ | | T06 | Sarhul | FIDT06 | ❌ | | T07 | Wangala | FIDT07 | ❌ |

Note: FID is case-insensitive. FIDH05, fidh05, and FidH05 all work — but FIDH05 is the recommended format.

📥 Importing

CommonJS (Node.js)

const { getFestivalByFID, getUpcomingFestivals } = require('indian-festivals');

ES Modules

import { getFestivalByFID, getUpcomingFestivals } from 'indian-festivals';

TypeScript

import { getFestivalByFID, Festival } from 'indian-festivals';

🔑 API Reference

🗺️ Festival Maps

| Export | Type | Description | |--------|------|-------------| | festivalsById | Map<string, Festival> | Fast O(1) lookup by festival id | | festivalsByReligion | Record<string, Festival[]> | All festivals grouped by religion |

import { festivalsById, festivalsByReligion } from 'indian-festivals';

// O(1) fast lookup
const diwali = festivalsById.get("diwali");

// All Hindu festivals grouped
const hindu = festivalsByReligion["Hindu"];

🔍 Festival Lookup

| Function | Returns | Description | |----------|---------|-------------| | getFestivalBySlug(slug) | Festival \| undefined | Get by slug | | getFestivalByName(name) | Festival \| undefined | Get by name or alternate name | | getFestivalByCode(code) | Festival \| undefined | Get by internal code e.g. H05 | | getFestivalByFestivalCode(code) | Festival \| undefined | Get by festival code e.g. DIWALI | | festivalExists(slug) | boolean | Check if a festival exists |

import { getFestivalBySlug, getFestivalByName, getFestivalByCode, festivalExists } from 'indian-festivals';

// By slug
const diwali = getFestivalBySlug("diwali");
console.log(diwali?.name);         // "Diwali"
console.log(diwali?.dates[2025]);  // "2025-10-20"
console.log(diwali?.religion);     // "Hindu"
console.log(diwali?.durationDays); // 5

// By name or alternate name
getFestivalByName("Deepavali");           // finds Diwali
getFestivalByName("Festival of Lights"); // also finds Diwali

// By internal code
getFestivalByCode("H05");  // Diwali
getFestivalByCode("N09");  // Republic Day

// Check existence
festivalExists("holi");   // true
festivalExists("xyz");    // false

🆔 FID Utilities

| Function | Returns | Description | |----------|---------|-------------| | getFestivalByFID(fid) | Festival \| undefined | Get single festival by FID | | getFestivalsByFIDs(fids) | Festival[] | Get multiple festivals by FID array |

import { getFestivalByFID, getFestivalsByFIDs } from 'indian-festivals';

// Single FID lookup
const diwali = getFestivalByFID("FIDH05");
console.log(diwali?.name);         // "Diwali"
console.log(diwali?.dates[2025]);  // "2025-10-20"

// FID is case-insensitive
getFestivalByFID("FIDH05"); // ✅ recommended
getFestivalByFID("fidh05"); // ✅ works
getFestivalByFID("FidH05"); // ✅ works

// Multiple FIDs — perfect for travel itineraries!
const festivals = getFestivalsByFIDs(["FIDH05", "FIDH12", "FIDS01", "FIDN05"]);
festivals.forEach(f => console.log(`${f.name} → ${f.dates[2025]}`));
// Diwali        → 2025-10-20
// Holi          → 2025-03-14
// Baisakhi      → 2025-04-13
// Independence Day → 2025-08-15

🕉️ Religion-based Utilities

| Function | Returns | Description | |----------|---------|-------------| | getFestivalsByReligion(religion) | Festival[] | All festivals of a religion | | getFestivalsByReligions(religions) | Festival[] | Festivals of multiple religions | | getFestivalCountByReligion() | Record<string, number> | Count grouped by religion | | getAvailableReligions() | string[] | All unique religions in dataset | | getPublicHolidays() | Festival[] | All public holidays | | getRestrictedHolidays() | Festival[] | All restricted holidays |

import { getFestivalsByReligion, getFestivalsByReligions, getFestivalCountByReligion, getAvailableReligions, getPublicHolidays } from 'indian-festivals';

// Single religion
const hinduFests = getFestivalsByReligion("Hindu");
console.log(hinduFests.length); // 28

// Multiple religions
const sikhAndJain = getFestivalsByReligions(["Sikh", "Jain"]);

// Count by religion
const counts = getFestivalCountByReligion();
console.log(counts);
// {
//   Hindu: 28, Islamic: 5, Christian: 5,
//   Sikh: 6, Jain: 5, Buddhist: 4,
//   National: 10, Tribal: 7
// }

// Available religions
getAvailableReligions();
// ["Buddhist", "Christian", "Hindu", "Islamic", "Jain", "National", "Sikh", "Tribal"]

// Public holidays only
const holidays = getPublicHolidays();
console.log(holidays.length); // 24

📅 Month & Date Utilities

| Function | Returns | Description | |----------|---------|-------------| | getFestivalsByMonth(month, year) | Festival[] | Festivals in a specific month and year | | getFestivalsByMonthAllYears(month) | Festival[] | Festivals in a month across all years | | getFestivalsInDateRange(start, end, year) | Festival[] | Festivals within a date range | | getFestivalsOnDate(date) | Festival[] | Festivals on a specific date | | getFullFestivalsByMonth(month, year) | { festival, date }[] | Festivals with dates, sorted | | getAvailableYears() | number[] | All years with festival data | | monthNames | string[] | Array of month names (constant) |

import { getFestivalsByMonth, getFestivalsOnDate, getFestivalsInDateRange, getFullFestivalsByMonth, getAvailableYears, monthNames } from 'indian-festivals';

// Festivals in October 2025
const oct = getFestivalsByMonth(10, 2025);
console.log(`${monthNames[9]} has ${oct.length} festivals`); // "October has 5 festivals"

// Festivals on a specific date
const onDiwali = getFestivalsOnDate("2025-10-20");
onDiwali.forEach(f => console.log(f.name)); // "Diwali"

// Festivals in a date range
const festiveSeaon = getFestivalsInDateRange("2025-10-01", "2025-11-30", 2025);
festiveSeaon.forEach(f => console.log(`${f.name} → ${f.dates[2025]}`));
// Dussehra       → 2025-10-02
// Dhanteras      → 2025-10-18
// Diwali         → 2025-10-20
// Govardhan Puja → 2025-10-21
// Bhai Dooj      → 2025-10-23

// Full festival objects with sorted dates
const full = getFullFestivalsByMonth(10, 2025);
full.forEach(({ festival, date }) => console.log(`${date}: ${festival.name}`));

// Available years
getAvailableYears(); // [2025, 2026, 2027, 2028, 2029, 2030]

⏰ Upcoming Festival Utilities

| Function | Returns | Description | |----------|---------|-------------| | getUpcomingFestivals(limit?) | { festival, date, daysUntil }[] | Next N upcoming festivals (default: 10) | | getNextFestival() | { festival, date, daysUntil } \| undefined | The very next festival | | getTodaysFestivals() | Festival[] | Festivals happening today | | getThisWeeksFestivals() | { festival, date, daysUntil }[] | Festivals in next 7 days | | getThisMonthsFestivals() | Festival[] | Festivals this month |

import { getUpcomingFestivals, getNextFestival, getTodaysFestivals, getThisWeeksFestivals } from 'indian-festivals';

// Next 5 upcoming festivals
const upcoming = getUpcomingFestivals(5);
upcoming.forEach(({ festival, date, daysUntil }) => {
  console.log(`${festival.name} - ${date} (${daysUntil} days away)`);
});
// Dussehra         - 2025-10-02 (1 days away)
// Karwa Chauth     - 2025-10-10 (9 days away)
// Dhanteras        - 2025-10-18 (17 days away)
// Diwali           - 2025-10-20 (19 days away)
// Govardhan Puja   - 2025-10-21 (20 days away)

// Very next festival
const next = getNextFestival();
console.log(`Next: ${next?.festival.name} in ${next?.daysUntil} days`);

// Today's festivals
const today = getTodaysFestivals();
if (today.length === 0) console.log("No festivals today");

// This week
const week = getThisWeeksFestivals();
week.forEach(({ festival, daysUntil }) => {
  console.log(`${festival.name} in ${daysUntil} days`);
});

🔎 Search & Filter Utilities

| Function | Returns | Description | |----------|---------|-------------| | searchFestivals(query) | { festival, matchScore }[] | Search with relevance score | | filterFestivals(filters) | Festival[] | Filter by multiple criteria | | getFestivalsByState(state) | Festival[] | Festivals celebrated in a state | | getFestivalsByRegion(region) | Festival[] | Festivals by region | | getFestivalsByType(type) | Festival[] | Festivals by type (LUNAR, FIXED) | | getFestivalsByCategory(category) | Festival[] | Festivals by category | | getAllRegions() | string[] | All unique regions | | getAllStates() | string[] | All unique states | | getAllTypes() | string[] | All unique types | | getRelatedFestivals(slug) | Festival[] | Related festivals | | getFestivalCount() | number | Total festival count |

import { searchFestivals, filterFestivals, getFestivalsByState } from 'indian-festivals';

// Search with relevance score
const results = searchFestivals("light");
results.slice(0, 3).forEach(({ festival, matchScore }) => {
  console.log(`${festival.name}: ${matchScore}`);
});
// Diwali: 180  (matches name + "Festival of Lights" + keywords)
// Kali Puja: 40

// Advanced filter
const filtered = filterFestivals({
  religion: "Hindu",
  isPublicHoliday: true,
  state: "Maharashtra"
});
filtered.forEach(f => console.log(f.name));
// Holi, Ganesh Chaturthi, Diwali, Dussehra...

// Filter by duration — multi-day festivals only
const multiDay = filterFestivals({ minDuration: 2 });
multiDay.forEach(f => console.log(`${f.name} (${f.durationDays} days)`));
// Navratri (9 days), Diwali (5 days), Paryushana (8 days)...

// Festivals in a state
getFestivalsByState("West Bengal");
getFestivalsByState("Kerala");

// Total count
console.log(`Total festivals: ${getFestivalCount()}`); // 70+

💡 Usage Examples

FID Lookup

import { getFestivalByFID, getFestivalsByFIDs } from 'indian-festivals';

// Get a single festival by FID
const diwali = getFestivalByFID("FIDH05");
console.log(diwali?.name); // "Diwali"

// Get multiple festivals by FIDs — perfect for travel itineraries!
const festivals = getFestivalsByFIDs(["FIDH05", "FIDH12", "FIDS01"]);
// Returns [Diwali, Holi, Baisakhi] — complete data for all three

Festival Lookup

import { getFestivalBySlug, getFestivalByName, festivalExists } from 'indian-festivals';

getFestivalBySlug("diwali");
getFestivalByName("Deepavali");   // also checks alternateNames
festivalExists("holi");           // true

Religion-based

import { getFestivalsByReligion, getFestivalsByReligions, getFestivalCountByReligion } from 'indian-festivals';

getFestivalsByReligion("Hindu");
getFestivalsByReligions(["Hindu", "Sikh"]);
getFestivalCountByReligion();
// { Hindu: 28, Islamic: 5, Christian: 5, ... }

Month & Date

import { getFestivalsByMonth, getFestivalsOnDate, getFestivalsInDateRange } from 'indian-festivals';

// All festivals in October 2025
getFestivalsByMonth(10, 2025);

// Festivals on a specific date
getFestivalsOnDate("2025-10-20");

// Festivals in a date range
getFestivalsInDateRange("2025-10-01", "2025-12-31", 2025);

Upcoming Festivals

import { getUpcomingFestivals, getNextFestival, getTodaysFestivals } from 'indian-festivals';

getUpcomingFestivals(5);   // next 5 festivals
getNextFestival();         // the very next one
getTodaysFestivals();      // festivals today
getThisWeeksFestivals();   // festivals this week
getThisMonthsFestivals();  // festivals this month

Search & Filter

import { searchFestivals, filterFestivals, getFestivalsByState } from 'indian-festivals';

// Search by keyword
searchFestivals("light");  // returns Diwali, etc.

// Filter by multiple criteria
filterFestivals({
  religion: "Hindu",
  isPublicHoliday: true,
  state: "Maharashtra"
});

// Festivals in a specific state
getFestivalsByState("West Bengal");

Full Implementation Example

import {
  getFestivalByFID,
  getFestivalsByFIDs,
  getUpcomingFestivals,
  getFestivalsByState,
  searchFestivals,
  getFestivalCountByReligion
} from 'indian-festivals';

// Travel itinerary — get complete data for selected festivals
const itinerary = getFestivalsByFIDs(["FIDH05", "FIDH12", "FIDS01", "FIDN05"]);
console.log(itinerary.map(f => `${f.name} → ${f.dates[2025]}`));

// Dashboard — upcoming festivals
const upcoming = getUpcomingFestivals(10);

// State page — festivals in Kerala
const keralaFestivals = getFestivalsByState("Kerala");

// Search
const results = searchFestivals("harvest");

// Stats
const stats = getFestivalCountByReligion();
console.log(stats);
// { Hindu: 28, Islamic: 5, Christian: 5, Sikh: 6, ... }

🗂️ Festival Data Structure

Each festival contains the following fields:

{
  id: string;              // "diwali"
  code: string;            // "H05" — internal code
  slug: string;            // "diwali"
  festivalCode: string;    // "DIWALI"

  name: string;            // "Diwali"
  alternateNames: string[];// ["Deepavali", "Festival of Lights"]

  religion: string;        // "Hindu"
  regions: string[];       // ["Pan India"]
  category: string;        // "Religious"
  type: string;            // "LUNAR" | "FIXED"

  states: string[];        // All states where celebrated
  districts: string[];

  description: string;
  significance: string;
  history: string;

  dates: {                 // Dates from 2025 to 2030
    2025: string;          // "2025-10-20"
    2026: string;
    2027: string;
    2028: string;
    2029: string;
    2030: string;
  };

  hinduCalendar: {
    month: string;         // "Kartika"
    paksha: string;        // "Krishna Paksha"
    tithi: string;         // "Amavasya"
  };

  islamicCalendar: {
    day: number | null;
    month: string;
  };

  isPublicHoliday: boolean;
  isRestrictedHoliday: boolean;
  durationDays: number;

  customs: string[];
  foods: string[];
  rituals: string[];

  relatedFestivals: string[];

  image: string;
  images: string[];
  video: string;
  videos: string[];

  wikipedia: string;
  officialSources: string[];
  keywords: string[];
  popularity: string[];
}

🌐 Works With

| Environment | Support | |--------------------|---------| | Node.js (CommonJS) | ✅ | | Node.js (ESM) | ✅ | | TypeScript | ✅ | | React | ✅ | | Next.js | ✅ | | Vite | ✅ | | Plain JavaScript | ✅ |

🤝 Contributing

Contributions, feature requests, and suggestions are welcome!

If you'd like to add new festivals, fix dates, improve descriptions, or add new utility functions, feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Kuntal Ojha

• GitHub: @kuntalojha
• npm: @mrkuntalojha
• LinkedIn: @mrkuntalojha
• X (Twitter): @kuntalojha
• Instagram: @mrkuntalojha
• YouTube: @kuntalojha

❤️ Support the Project

Your support helps maintain and expand the festival database with more festivals, better coverage, and future years.