Hijri
Hijri ⇄ Gregorian on the real Umm al-Qura table — and honest about where the table ends.
npm install @devix-labs/hijri
The Umm al-Qura calendar is a published table, not a formula, so this package ships the table: read out of ICU at build time, checked against it day by day, and verified again on every build by comparing every week of a century. Outside 1300–1600 AH the tabular calendar answers and the result says exact: false. Whole-day offsets for countries that sight the moon a day either way, Arabic, Urdu and English names and numerals, parsing of what people type, and the dates everyone asks for — Ramadan, both Eids, Ashura, Mawlid, Laylat al-Qadr and Arafah.
What you get
The published table, not a formula
Read out of ICU at build time and checked day by day, so the conversion is the calendar governments actually print.
Honest about its edges
Outside 1300–1600 AH it uses the tabular calendar and marks the result exact: false. Nothing else in this space tells you.
Offsets, because the moon is sighted
Ministries publish “one day ahead of Umm al-Qura”. A whole-day offset applies to both directions, so the month lengths stay right.
Arabic, Urdu and English
Month and weekday names, Arabic-Indic and Persian numerals, and parsing that accepts a month name from any of the three.
The dates people ask for
Ramadan, both Eids, Ashura, Mawlid, Isra and Mi'raj, Laylat al-Qadr and Arafah — with Gregorian dates and a countdown.
4 KB and no Intl at runtime
Works in a worker, an old browser, or anywhere ICU data has been trimmed out. moment-hijri needs a deprecated library to run at all.
Hijri — overview
Why it exists
The Umm al-Qura calendar is not calculable. It is a table of month lengths decided in advance by the Saudi authority, and any library that derives it from a formula is approximating — usually by a day, sometimes for a month at a time.
The JavaScript options are moment-hijri, which needs the deprecated moment; @umalqura/core, last released in 2019; and hijri-converter, last released in 2018.
What it does differently
- The real table, read out of ICU at build time and checked day by day, so there is no runtime
dependency on
Intl— it works in a worker, an old browser, or anywhere ICU data is trimmed. - Honest edges. Outside 1300–1600 AH it says
exact: falseand uses the tabular calendar. - Offsets, because a sighting a day either way is normal and every ministry publishes its own.
- Arabic, Urdu and English names and numerals, and parsing of what people actually type.
- The dates people want: Ramadan, both Eids, Ashura, Mawlid, Laylat al-Qadr, Arafah.
Not in 1.0
Sighting-based calendars that differ by country beyond a whole-day offset, and the Persian and Ottoman calendars. A PHP twin is planned.
How it compares
Questions
Why ship a table instead of calculating it?
Because Umm al-Qura is not calculable. Month lengths are decided in advance and published by the Saudi authority; a formula can only approximate them, usually to within a day. The table here is read out of ICU once and checked against it, so it is the calendar that is actually printed.
What happens outside 1300–1600 AH?
The tabular calendar answers and the result carries exact: false. Show that if the date matters — a birth certificate for 1250 AH is not something any library can convert authoritatively.
My country's Eid is a day later than this says.
That is normal: most countries sight the moon and announce. Pass offset: 1 (or -1) to follow a particular authority; it applies to both directions so the arithmetic stays consistent. Calendar dates are always "expected" until the announcement.
How does it compare with moment-hijri?
moment-hijri needs moment, which its own maintainers have deprecated since 2020. @umalqura/core has had no release since 2019 and hijri-converter since 2018. This is 4 KB, has no dependencies, needs no Intl at runtime, and is checked against ICU on every build.
Does it do prayer times?
No — that is @devix/prayer-times, which is a separate package so neither carries the other's weight.
More from Devix
All resources →Prayer Times
Library
Prayer times and Qibla direction with every calculation method.
VAT Calculator
Library
VAT and GST maths for the UAE, Saudi Arabia and Pakistan.
Arabic Slugify
Library
Slugs and transliteration for Arabic and Urdu text.