5.1 KiB
API Reference
Installation
pnpm add moment moment-hijri-plus hijri-core
moment and hijri-core are peer dependencies. Both must be installed.
Plugin installation
import moment from 'moment';
import installHijri from 'moment-hijri-plus';
// Call once at application startup.
installHijri(moment);
After this call, all methods below are available on every moment instance and on the moment constructor itself.
Instance methods
toHijri(options?)
Converts the moment to a Hijri date.
Signature: (options?: ConversionOptions) => HijriDate | null
Returns null if the date falls outside the supported calendar range (UAQ covers AH 1318-1500, approximately CE 1900-2076).
const h = moment(new Date(2023, 2, 23)).toHijri();
// => { hy: 1444, hm: 9, hd: 1 }
const h = moment(new Date(2023, 2, 23)).toHijri({ calendar: 'fcna' });
HijriDate fields:
| Field | Type | Description |
|---|---|---|
hy |
number |
Hijri year |
hm |
number |
Hijri month (1 = Muharram, 12 = Dhul Hijjah) |
hd |
number |
Hijri day (1-30) |
hijriYear(options?)
Signature: (options?: ConversionOptions) => number | null
moment(new Date(2023, 2, 23)).hijriYear(); // => 1444
hijriMonth(options?)
Signature: (options?: ConversionOptions) => number | null
Returns 1-12 (1 = Muharram).
moment(new Date(2023, 2, 23)).hijriMonth(); // => 9 (Ramadan)
hijriDay(options?)
Signature: (options?: ConversionOptions) => number | null
moment(new Date(2023, 2, 23)).hijriDay(); // => 1
isValidHijri(options?)
Signature: (options?: ConversionOptions) => boolean
Returns true if the date falls within the supported range of the chosen calendar.
moment(new Date(2023, 2, 23)).isValidHijri(); // => true
moment(new Date(1900, 0, 1)).isValidHijri(); // => false (before UAQ range)
formatHijri(formatStr, options?)
Signature: (formatStr: string, options?: ConversionOptions) => string
Format using Hijri-aware tokens. All tokens not listed below are passed through to moment.format(), so Gregorian tokens work as normal.
Returns '' if the date is outside the Hijri range.
moment(new Date(2023, 2, 23)).formatHijri('iD iMMMM iYYYY AH');
// => '1 Ramadan 1444 AH'
moment(new Date(2023, 2, 23)).formatHijri('iYYYY-iMM-iDD');
// => '1444-09-01'
// Mix Hijri and Gregorian tokens.
moment(new Date(2023, 2, 23)).formatHijri('iD iMMMM iYYYY [CE:] MMMM D, YYYY');
// => '1 Ramadan 1444 CE: March 23, 2023'
Format tokens:
| Token | Example output | Description |
|---|---|---|
iYYYY |
1444 |
Hijri year, 4+ digits, zero-padded to 4 |
iYY |
44 |
Hijri year, last 2 digits, zero-padded |
iMMMM |
Ramadan |
Month long name |
iMMM |
Ramadan |
Month medium name |
iMM |
09 |
Month number, zero-padded |
iM |
9 |
Month number |
iDD |
01 |
Day, zero-padded |
iD |
1 |
Day |
iEEEE |
Yawm al-Khamis |
Weekday long name |
iEEE |
Kham |
Weekday short name |
iE |
5 |
Weekday numeric (1=Sunday, 7=Saturday) |
ioooo |
AH |
Era, long |
iooo |
AH |
Era, short |
Static methods
moment.fromHijri(hy, hm, hd, options?)
Signature: (hy: number, hm: number, hd: number, options?: ConversionOptions) => Moment
Creates a moment from a Hijri date. Throws Error if the date is invalid or outside the calendar range.
const m = moment.fromHijri(1444, 9, 1);
m.format('YYYY-MM-DD'); // => '2023-03-23'
// With FCNA calendar.
const m2 = moment.fromHijri(1444, 9, 1, { calendar: 'fcna' });
Options
interface ConversionOptions {
calendar?: string; // default: 'uaq'
}
| Calendar ID | Description |
|---|---|
uaq |
Umm al-Qura: official Saudi calendar, tabular, covers AH 1318-1500 |
fcna |
FCNA/ISNA: Fiqh Council of North America calculated calendar |
Custom calendars can be registered with hijri-core's registerCalendar().
TypeScript
All methods are typed via module augmentation. Import types from this package:
import type { HijriDate, ConversionOptions } from 'moment-hijri-plus';