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' };

Documentation

Full API reference, architecture notes, and examples: Wiki

Related Packages

• 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

License

MIT. Copyright (c) 2026 Aric Camarata.