quickstart

Quick Start

This guide covers the most common use cases in date-fns-hijri. All examples use the default Umm al-Qura (UAQ) calendar. For FCNA/ISNA calendar output, pass { calendar: 'fcna' } as the last argument to any function.

Installation

pnpm add date-fns-hijri hijri-core

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

Convert a Gregorian date to Hijri

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

const date = new Date(2023, 2, 23); // March 23, 2023
const hijri = toHijriDate(date);
// { hy: 1444, hm: 9, hd: 1 }

toHijriDate returns null for dates outside the UAQ table range (1318-1500 AH, approximately 1900-2076 CE). Always check for null before using the result.

Convert a Hijri date to Gregorian

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

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

Format a Hijri date

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

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

Supported format tokens:

Token	Output
iYYYY	Hijri year (4 digits)
iYY	Hijri year (2 digits)
iMM	Month number (01-12)
iMMM	Short month name
iMMMM	Full month name
iDD	Day (01-30)
iD	Day (1-30)

Get a month name

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

const name = getHijriMonthName(9);
// 'Ramadan'

const shortName = getHijriMonthName(9, { format: 'short' });
// 'Ram'

Add months in Hijri space

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

const ramadan = new Date(2023, 2, 23); // 1 Ramadan 1444
const shawwal = addHijriMonths(ramadan, 1);
// Date representing 1 Shawwal 1444 (April 21, 2023)

Month arithmetic respects variable-length Hijri months (29 or 30 days depending on the calendar).

Use the FCNA calendar

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

const opts = { calendar: 'fcna' };
const hijri = toHijriDate(new Date(2023, 2, 23), opts);
const label = formatHijriDate(new Date(2023, 2, 23), 'iDD iMMMM iYYYY', opts);

FCNA (Fiqh Council of North America) uses astronomical new moon calculation rather than the Umm al-Qura table. Results may differ by one day around month boundaries.

CommonJS

const { toHijriDate, fromHijriDate, formatHijriDate } = require('date-fns-hijri');

const hijri = toHijriDate(new Date(2023, 2, 23));

Next steps

• API Reference for the full function list and signatures
• Architecture for how the calendar engine and format layer work
• Advanced Guide for error handling, range validation, and locale patterns