Building a Hijri-Gregorian Date Calculator: Lessons from an Arabic Web Tool

Saad Tahir — Tue, 30 Jun 2026 20:51:37 +0000

If you've ever tried to build a date calculator for Arabic-speaking users, you've likely run into one frustrating problem: the Gregorian calendar isn't the only game in town.

Across Saudi Arabia, the Gulf, and much of the Arab world, the Hijri (Islamic) calendar is used daily — for religious occasions, official government documents, birth certificates, and even age verification. Building agecalculator360.com taught me a lot about these differences.

What Makes the Hijri Calendar Different?

The Hijri calendar is a purely lunar calendar, meaning:

Each month starts with the new crescent moon
Months alternate between 29 and 30 days
A Hijri year is approximately 354 days — about 11 days shorter than a Gregorian year
This means a person's Hijri age is always slightly older than their Gregorian age

This also means date conversion isn't a simple formula. You can't just multiply by a constant.

The Two Hijri Systems

This is where it gets tricky. There are actually two main Hijri calendar systems used in software:

1. The Tabular Islamic Calendar

A purely algorithmic calendar used by most JavaScript libraries. It follows a fixed 30-year cycle pattern. It's consistent, but it can be off by 1–2 days from the official calendar used in Saudi Arabia.

2. The Umm Al-Qura Calendar

The official calendar of Saudi Arabia, maintained by the King Abdulaziz City for Science and Technology (KACST). This one is based on astronomical calculations and is what all Saudi government systems use for official age verification.

If you're building tools for Saudi Arabia or the Gulf region, using the tabular system will give users wrong results on documents that matter.

JavaScript Implementation Challenges

Here's what I ran into building the Hijri age calculator:

No Standard Library

The most popular Hijri calendar libraries (moment-hijri, hijri-js) default to the tabular system. For the Umm Al-Qura calendar, you need to either:

Maintain a lookup table of month lengths (which KACST publishes)
Implement the astronomical algorithm yourself

I opted for the lookup table approach, which makes the code larger but guarantees accuracy for current and near-future dates.

Age Calculation Edge Cases

Computing someone's age in Hijri has a subtle edge case: because Hijri months vary in length (29 or 30 days), two people born on the "same day" in different years might have different day counts in their birth month.

function hijriAge(birthYear, birthMonth, birthDay, todayYear, todayMonth, todayDay) {
  let years = todayYear - birthYear;
  let months = todayMonth - birthMonth;
  let days = todayDay - birthDay;

  if (days < 0) {
    months--;
    // Get days in previous Hijri month (29 or 30, not fixed!)
    days += getHijriMonthLength(todayYear, todayMonth - 1);
  }
  if (months < 0) {
    years--;
    months += 12;
  }
  return { years, months, days };
}

The getHijriMonthLength() function is what requires the Umm Al-Qura lookup table — you can't calculate it from a formula alone.

Dual Calendar Display

Many Arabic users want to see their age in both calendars simultaneously. This is actually a feature, not a complication. Our date converter tool shows both Hijri and Gregorian equivalents side by side.

The UX lesson: don't make users choose. Show both.

RTL and Arabic Numeral Considerations

A quick note on display: if you're building for Arabic audiences, remember:

Use Western digits (0-9), not Eastern Arabic digits (٠-٩) — most Arabic users prefer Western digits in numeric contexts
The dir="rtl" attribute on your HTML element handles text direction
Google Fonts has excellent Arabic-supporting fonts: Cairo and Readex Pro are both readable and load fast

The Result

After working through these challenges, the tool now handles:

Age calculation in both Hijri and Gregorian simultaneously
Support for dates back to 1930 CE / 1348 AH
School enrollment age calculation based on Saudi education ministry rules
Retirement age calculation for Saudi Arabia and 6 other Arab countries

If you're building date tools for the Arab world, I hope this saves you some debugging time!

DEV Community: Saad Tahir