date-fns-hijri

date-fns-style functions for Hijri calendar operations. Works with any date library.

Each function is a pure, stateless utility. No classes. No configuration object. Pass a Date, get a result. Pass options to switch calendar systems. The API mirrors date-fns conventions so the learning curve is minimal.

Installation

pnpm add date-fns-hijri hijri-core

hijri-core is a peer dependency. It provides the underlying calendar engine and must be installed alongside this package.

Quick Start

import {
  toHijriDate,
  fromHijriDate,
  formatHijriDate,
  addHijriMonths,
  getHijriMonthName,
} from 'date-fns-hijri';

// Convert a Gregorian date to Hijri
const hijri = toHijriDate(new Date(2023, 2, 23));
// { hy: 1444, hm: 9, hd: 1 } - 1 Ramadan 1444

// Convert back
const gregorian = fromHijriDate(1444, 9, 1);
// Date: 2023-03-23T00:00:00.000Z

// Format with Hijri tokens
const label = formatHijriDate(new Date(2023, 2, 23), 'iDD iMMMM iYYYY');
// '01 Ramadan 1444'

// Get the month name directly
const name = getHijriMonthName(9);
// 'Ramadan'

// Add months in the Hijri calendar
const nextMonth = addHijriMonths(new Date(2023, 2, 23), 1);
// Date in Shawwal 1444

API

All functions accept an optional options argument for selecting the calendar system. When omitted, Umm al-Qura (UAQ) is used.

Conversion

Function	Signature	Description
toHijriDate	(date: Date, options?) => HijriDate | null	Convert Gregorian to Hijri. Returns null if out of range.
fromHijriDate	(hy, hm, hd, options?) => Date	Convert Hijri to Gregorian. Throws if invalid.

Validation

Function	Signature	Description
isValidHijriDate	(hy, hm, hd, options?) => boolean	Check if a Hijri date exists in the calendar table.

Field Getters

Function	Signature	Description
getHijriYear	(date, options?) => number | null	Hijri year. Null if out of range.
getHijriMonth	(date, options?) => number | null	Hijri month (1-12). Null if out of range.
getHijriDay	(date, options?) => number | null	Hijri day of month. Null if out of range.
getDaysInHijriMonth	(hy, hm, options?) => number	Days in a Hijri month (29 or 30).
getHijriQuarter	(date, options?) => number | null	Quarter (1-4). Null if out of range.

Names

Function	Signature	Description
getHijriMonthName	(hm, length?) => string	English month name. length: 'long' (default), 'medium', 'short'.
getHijriWeekdayName	(date, length?) => string	Arabic weekday name. length: 'long' (default), 'short'.

Formatting

Function	Signature	Description
formatHijriDate	(date, formatStr, options?) => string	Format a date with Hijri tokens. Returns '' if out of range.

Arithmetic

Function	Signature	Description
addHijriMonths	(date, months, options?) => Date	Add N Hijri months. Clamps day to month length.
addHijriYears	(date, years, options?) => Date	Add N Hijri years. Clamps day to month length.

Month Boundaries

Function	Signature	Description
startOfHijriMonth	(date, options?) => Date	First day of the containing Hijri month.
endOfHijriMonth	(date, options?) => Date	Last day of the containing Hijri month.

Comparisons

Function	Signature	Description
isSameHijriMonth	(dateA, dateB, options?) => boolean	Both dates in the same Hijri month.
isSameHijriYear	(dateA, dateB, options?) => boolean	Both dates in the same Hijri year.

Calendar Systems

Two calendar systems are available via the options.calendar property.

Umm al-Qura (default): The official calendar of Saudi Arabia. Covers 1318–1500 AH (1900–2076 CE). Tabular data; deterministic.

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

const uaq = toHijriDate(new Date(2023, 2, 23));
// uses UAQ by default

FCNA/ISNA: The calendar used by the Fiqh Council of North America. Astronomical calculation; extends slightly beyond UAQ's range.

const fcna = toHijriDate(new Date(2023, 2, 23), { calendar: 'fcna' });

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	09
iM	Month number	9
iDD	Zero-padded day	01
iD	Day number	1
iEEEE	Long weekday name	Yawm al-Khamis
iEEE	Short weekday name	Kham
iE	Numeric weekday (1=Sun)	5
ioooo	Long era	AH
iooo	Short era	AH

Non-token text in the format string passes through unchanged:

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

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

TypeScript

Full type definitions are included. Re-exported from hijri-core:

import type { HijriDate, ConversionOptions } from 'date-fns-hijri';

const h: HijriDate = { hy: 1444, hm: 9, hd: 1 };
const opts: ConversionOptions = { calendar: 'fcna' };

Architecture

A thin adapter over hijri-core. Each function is a stateless wrapper that delegates to the registered calendar engine. No global state, no configuration object: pass options per call.

For more detail see the Architecture wiki page.

Documentation

Full API reference, architecture notes, and examples: Wiki

Related

• hijri-core - Zero-dependency Hijri engine powering this library
• luxon-hijri - Hijri support for Luxon DateTime objects
• pray-calc - Islamic prayer times
• nrel-spa - Solar position algorithm

Compatibility

• Node.js 20, 22, 24
• ESM and CJS builds included
• TypeScript definitions bundled
• Works in browsers and all major bundlers

Acknowledgments

Calendar data and algorithms provided by hijri-core. The Umm al-Qura table is derived from data published by the King Abdulaziz City for Science and Technology (KACST). FCNA new moon calculations follow Jean Meeus, "Astronomical Algorithms," 2nd ed., Chapter 49.

License

MIT. Copyright (c) 2026 Aric Camarata.