advanced

Advanced Usage

Switching calendars per call

Each method accepts an optional options argument:

import moment from 'moment';
import hijri from 'moment-hijri-plus';

moment.extend(hijri);

const m = moment('2023-03-23');

const uaqYear = m.iYear();               // UAQ (default)
const fcnaYear = m.iYear({ calendar: 'fcna' }); // FCNA

Near month boundaries, UAQ and FCNA may differ by one day.

Null safety

m.toHijri() returns null for dates outside UAQ range (approximately 1900-2076 CE). Guard before using:

const hijri = m.toHijri();
if (hijri !== null) {
  console.log(hijri.hy, hijri.hm, hijri.hd);
}

Combining with Moment.js locales

Moment.js locale settings affect Gregorian formatting but not Hijri tokens. Hijri tokens always produce the same English output regardless of locale. To localize Hijri month names, use getHijriMonthName from date-fns-hijri or build your own translation layer.

Formatting alongside Gregorian tokens

Hijri tokens (iYYYY, iMM, iDD, iMMMM, etc.) coexist with Moment Gregorian tokens:

m.format('YYYY-MM-DD (iD iMMMM iYYYY)');
// '2023-03-23 (1 Ramadan 1444)'

Moment.js tree-shaking

Moment.js does not tree-shake well. If bundle size is a concern in a new project, consider migrating to Day.js + dayjs-hijri-plus for the same Hijri API with significantly smaller bundles.

TypeScript augmentation

The plugin augments Moment.js type definitions automatically:

import moment from 'moment';
import hijri from 'moment-hijri-plus';

moment.extend(hijri);

const m = moment('2023-03-23');
const year: number = m.iYear(); // fully typed