Persian Holidays

Look up official, religious, and cultural Iranian holidays for a single date, a range, or a whole calendar year. Jalali and Gregorian entries resolve to an exact date; Hijri (lunar) entries are resolved with a tabular approximation and flagged approximate: true, since Iran announces religious holidays by moon sighting.

Last updated August 12, 2026

CreditsModifiedPublished

Copied from BaseMax/persian-holidays-api.

Trimmed the dataset to recurring month/day entries (dropped year-specific fields).
Converted month names to numeric, 1-indexed month indices.
Added a tabular Hijri→Gregorian resolution with approximate flagging for lunar entries.
Added official/includeUnofficial filtering so callers can request only official days off.

Overview

Installation

$ npx shadcn@latest add https://ui.persian-labs.ir/r/persian-holidays.json

Usage

import { getHolidays, isHoliday } from "@/lib/persian-holidays"
import { today } from "@/lib/persian-date"
 
const holidays1404 = getHolidays(1404) // Jalali year 1404
const isTodayOff = isHoliday(today())

Examples

Lookup a date

isHoliday and getHolidayInfo check whether a specific date is a holiday, and list every matching entry.

Official vs. unofficial

By default only official days off are returned. Pass includeUnofficial: true to also list commemorative occasions.

Calendar grid

getHolidaysInRange over a month's boundaries makes it easy to color holiday cells in a calendar grid.

Hijri approximation

Lunar (hijri) holidays resolve through a tabular approximation and come back with approximate: true — treat these dates as a best-effort estimate, not an announcement.

RTL

Holiday titles are Persian text end-to-end, so this reads naturally inside right-to-left layouts without any extra direction handling.

API Reference

persian-holidays

Prop	Type	Default	Description
getHolidays(year, calendarType?, options?)	(year: number, calendarType?: CalendarType, options?: GetHolidaysOptions) => ResolvedHoliday[]	"shamsi"	Convenience wrapper around getHolidaysInRange for a whole calendar year, e.g. getHolidays(1405) for Jalali year 1405, or getHolidays(2026, "miladi").
getHolidaysInRange(from, to, options?)	(from: Date, to: Date, options?: GetHolidaysOptions) => ResolvedHoliday[]	—	Resolves every holiday/occasion whose date falls within [from, to] (inclusive). A hijri (lunar) holiday can appear zero, one, or twice, since a lunar year is shorter than a solar one.
isHoliday(date, options?)	(date: Date, options?: GetHolidaysOptions) => boolean	—	True if date matches any (official, by default) holiday.
getHolidayInfo(date, options?)	(date: Date, options?: GetHolidaysOptions) => ResolvedHoliday[]	—	Every holiday/occasion that falls on date.

GetHolidaysOptions

Prop	Type	Default	Description
includeUnofficial	boolean	false	Include commemorative/unofficial occasions, not just official days off.

ResolvedHoliday

Prop	Type	Default	Description
calendar	"jalali" \| "gregorian" \| "hijri"	—	Which calendar the entry's month/day fields are defined in.
official	boolean	—	Whether this is an official day off, as opposed to a commemorative occasion.
title	string	—	Persian title of the holiday or occasion.
month	number	—	1-indexed month, in the entry's own calendar field above.
day	number	—	1-indexed day, in the entry's own calendar field above.
date	Date	—	The resolved Gregorian Date for this occurrence.
approximate	boolean	—	True for hijri (lunar) entries, which are resolved via a tabular approximation and can shift by up to a day from the real, moon-sighting-announced date.

Low-level Hijri helpers

Prop	Type	Default	Description
hijriToJdn(year, month, day)	(year: number, month: number, day: number) => number	—	Tabular ("civil"/Kuwaiti) Hijri calendar day → Julian Day Number.
jdnToGregorian(jdn)	(jdn: number) => Date	—	Julian Day Number → Gregorian calendar Date (local midnight), via the Fliegel & Van Flandern algorithm.
hijriMonthLength(year, month)	(year: number, month: number) => number	—	Number of days in a tabular Hijri month (29 or 30).

Edit this page on GitHub

PreviousPersian Date (Zod)NextPersian Reshape