date-fns-hijri/.wiki/API-Reference.md

API Reference

All functions accept an optional options?: ConversionOptions argument as their last parameter. When omitted, the Umm al-Qura (UAQ) calendar is used.

interface ConversionOptions {
  calendar?: string; // 'uaq' (default) | 'fcna'
}

---

Conversion

toHijriDate

function toHijriDate(date: Date, options?: ConversionOptions): HijriDate | null

Convert a Gregorian Date to a Hijri date object.

Returns null when the date falls outside the calendar's supported range. UAQ covers 1356-1500 AH (approximately 1937-2077 CE).

Parameters:

Name	Type	Description
date	Date	A valid Gregorian date
options	ConversionOptions	Optional. Calendar system selection

Returns: HijriDate | null

Example:

import { toHijriDate } from 'date-fns-hijri';

toHijriDate(new Date(2023, 2, 23, 12));
// { hy: 1444, hm: 9, hd: 1 } — 1 Ramadan 1444

toHijriDate(new Date(1800, 0, 1));
// null — out of range

---

fromHijriDate

function fromHijriDate(hy: number, hm: number, hd: number, options?: ConversionOptions): Date

Convert a Hijri date to a Gregorian Date.

The returned Date is set to midnight UTC of the equivalent Gregorian day.

Parameters:

Name	Type	Description
hy	number	Hijri year
hm	number	Hijri month (1-12)
hd	number	Hijri day (1-30)
options	ConversionOptions	Optional. Calendar system selection

Returns: Date

Throws: Error if the Hijri date is invalid or outside the supported range.

Example:

import { fromHijriDate } from 'date-fns-hijri';

fromHijriDate(1444, 9, 1);
// Date: 2023-03-23T00:00:00.000Z

fromHijriDate(1444, 13, 1);
// throws Error

---

Validation

isValidHijriDate

function isValidHijriDate(hy: number, hm: number, hd: number, options?: ConversionOptions): boolean

Check whether a Hijri date is valid. Verifies year, month (1-12), and day (1-daysInMonth) all exist in the calendar's data table.

Example:

isValidHijriDate(1444, 9, 1);   // true
isValidHijriDate(1444, 13, 1);  // false — no month 13
isValidHijriDate(1444, 9, 31);  // false — Ramadan has 29 or 30 days

---

Field Getters

getHijriYear

function getHijriYear(date: Date, options?: ConversionOptions): number | null

Get the Hijri year for a Gregorian date. Returns null when out of range.

---

getHijriMonth

function getHijriMonth(date: Date, options?: ConversionOptions): number | null

Get the Hijri month (1-12) for a Gregorian date. Returns null when out of range.

---

getHijriDay

function getHijriDay(date: Date, options?: ConversionOptions): number | null

Get the Hijri day of month for a Gregorian date. Returns null when out of range.

---

getDaysInHijriMonth

function getDaysInHijriMonth(hy: number, hm: number, options?: ConversionOptions): number

Get the number of days in a Hijri month. Returns 29 or 30.

Throws: Error if the year/month combination is outside the supported range.

Example:

getDaysInHijriMonth(1444, 9); // 29 or 30 (Ramadan 1444)
getDaysInHijriMonth(1444, 1); // 30 (Muharram 1444)

---

getHijriQuarter

function getHijriQuarter(date: Date, options?: ConversionOptions): number | null

Get the Hijri quarter (1-4) for a date. Months 1-3 = Q1, 4-6 = Q2, 7-9 = Q3, 10-12 = Q4.

Returns null when out of range.

Example:

getHijriQuarter(new Date(2023, 2, 23, 12)); // 3 (Ramadan = month 9 = Q3)

---

Names

getHijriMonthName

function getHijriMonthName(hm: number, length?: 'long' | 'medium' | 'short'): string

Get the English name of a Hijri month.

Parameters:

Name	Type	Default	Description
hm	number		Month number (1-12)
length	'long' | 'medium' | 'short'	'long'	Name length

Throws: RangeError if hm is not in [1, 12].

Month names by length:

Month	Long	Medium	Short
1	Muharram	Muharram	Muh
2	Safar	Safar	Saf
3	Rabi'l Awwal	Rabi1	Ra1
4	Rabi'l Thani	Rabi2	Ra2
5	Jumadal Awwal	Jumada1	Ju1
6	Jumadal Thani	Jumada2	Ju2
7	Rajab	Rajab	Raj
8	Sha'ban	Shaban	Shb
9	Ramadan	Ramadan	Ram
10	Shawwal	Shawwal	Shw
11	Dhul Qi'dah	Dhul-Qidah	DhQ
12	Dhul Hijjah	Dhul-Hijah	DhH

---

getHijriWeekdayName

function getHijriWeekdayName(date: Date, length?: 'long' | 'short'): string

Get the Arabic weekday name for a Gregorian date. Uses Date.getDay() (0 = Sunday through 6 = Saturday) as the index.

Weekday names:

JS getDay()	Day	Long	Short
0	Sunday	Yawm al-Ahad	Ahad
1	Monday	Yawm al-Ithnayn	Ithn
2	Tuesday	Yawm ath-Thulatha'	Thul
3	Wednesday	Yawm al-Arba`a'	Arba
4	Thursday	Yawm al-Khamis	Kham
5	Friday	Yawm al-Jum`a	Jum`a
6	Saturday	Yawm as-Sabt	Sabt

---

Formatting

formatHijriDate

function formatHijriDate(date: Date, formatStr: string, options?: ConversionOptions): string

Format a Gregorian date using Hijri calendar tokens.

Returns an empty string when the date falls outside the supported range. Non-token text passes through unchanged.

Format tokens:

Token	Output	Example
iYYYY	4-digit Hijri year	1444
iYY	2-digit Hijri year	44
iMMMM	Long month name	Ramadan
iMMM	Medium month name	Ramadan
iMM	Zero-padded month (01-12)	09
iM	Month (1-12)	9
iDD	Zero-padded day (01-30)	01
iD	Day (1-30)	1
iEEEE	Long weekday name	Yawm al-Khamis
iEEE	Short weekday name	Kham
iE	Numeric weekday (1=Sun, 7=Sat)	5
ioooo	Long era	AH
iooo	Short era	AH

Examples:

formatHijriDate(new Date(2023, 2, 23, 12), 'iYYYY-iMM-iDD');
// '1444-09-01'

formatHijriDate(new Date(2023, 2, 23, 12), 'iD iMMMM iYYYY ioooo');
// '1 Ramadan 1444 AH'

formatHijriDate(new Date(2023, 2, 23), 'iEEEE');
// 'Yawm al-Khamis'

---

Arithmetic

addHijriMonths

function addHijriMonths(date: Date, months: number, options?: ConversionOptions): Date

Add a number of Hijri months to a Gregorian date.

Handles year rollover automatically. If the resulting month has fewer days than the original day, the day is clamped to the last day of the new month. Accepts negative values to subtract months.

Throws: Error if the input or result is outside the supported range.

Example:

// 1 Ramadan 1444 + 1 month = 1 Shawwal 1444
addHijriMonths(new Date(2023, 2, 23, 12), 1);

// Month rollover: Dhul Hijjah + 1 = Muharram of next year
addHijriMonths(new Date(2023, 6, 18, 12), 1);

---

addHijriYears

function addHijriYears(date: Date, years: number, options?: ConversionOptions): Date

Add a number of Hijri years to a Gregorian date.

If the resulting year has fewer days in the same month (e.g., day 30 in a 29-day month), the day is clamped to the last valid day. Accepts negative values to subtract years.

Throws: Error if the input or result is outside the supported range.

---

Month Boundaries

startOfHijriMonth

function startOfHijriMonth(date: Date, options?: ConversionOptions): Date

Get the first day of the Hijri month that contains the given date.

Throws: Error if the date is outside the supported range.

---

endOfHijriMonth

function endOfHijriMonth(date: Date, options?: ConversionOptions): Date

Get the last day of the Hijri month that contains the given date.

Throws: Error if the date is outside the supported range.

Example:

// 1 Ramadan 1444 is March 23, 2023
const start = startOfHijriMonth(new Date(2023, 3, 1, 12));
// Date: 2023-03-23T00:00:00.000Z

const end = endOfHijriMonth(new Date(2023, 3, 1, 12));
// Date: last day of Ramadan 1444

---

Comparisons

isSameHijriMonth

function isSameHijriMonth(dateA: Date, dateB: Date, options?: ConversionOptions): boolean

Check whether two Gregorian dates fall in the same Hijri month.

Returns false if either date is outside the supported range.

---

isSameHijriYear

function isSameHijriYear(dateA: Date, dateB: Date, options?: ConversionOptions): boolean

Check whether two Gregorian dates fall in the same Hijri year.

Returns false if either date is outside the supported range.

Example:

// Both in Ramadan 1444
isSameHijriMonth(new Date(2023, 2, 23, 12), new Date(2023, 3, 10, 12)); // true

// 1444 vs 1446
isSameHijriYear(new Date(2023, 2, 23, 12), new Date(2024, 6, 7, 12)); // false

---

Home · API Reference · Architecture