Hijri calendar systems

Taqwim supports three deterministic Hijri calendar systems. Umm al-Qura is the backward-compatible default; Islamic Civil and Islamic TBLA are explicit arithmetic alternatives.

The choice matters. The same Gregorian day can have different Hijri fields in different systems, and the same { hy, hm, hd } fields can identify different absolute days. Choose one system for a stored date and keep that choice with it.

Choose a system

• Umm al-Qura (islamic-umalqura) — choose the compatible default for existing Taqwim applications and integrations that expect its supplied 1343–1500 AH table.
• Islamic Civil (islamic-civil) — choose the Friday-epoch arithmetic calendar for deterministic calculations beyond that table, or for an integration that names this identifier.
• Islamic TBLA (islamic-tbla) — choose the Thursday-epoch arithmetic calendar only when your data or integration specifically expects TBLA.

If an external contract, database or API names a calendar identifier, use that exact system. If it does not, do not infer one from the word “Hijri” alone.

Range modelUmm al-Qura is bounded by Taqwim's data. Civil and TBLA calculate dates in either direction.

Earlier1924Today2077Later

Umm al-Qura

1343–1500 AH

Islamic Civil

Proleptic arithmetic

Islamic TBLA

Proleptic arithmetic

Same fields, different epochCivil and TBLA use the same month and leap-year rules. Their starting day is different.

1 Muharram 1 AH→TBLA · Thursday epoch→18 July 622

1 Muharram 1 AH→Civil · Friday epoch→19 July 622

Gregorian dates are proleptic. For the same Hijri fields, TBLA resolves one day earlier than Civil.

How the systems differ

Umm al-Qura

Taqwim’s Umm al-Qura implementation reads month lengths from a bundled table. There is no formula to extend beyond the table, so conversion outside 1343–1500 AH throws HijriRangeError. This bounded behaviour is deliberate: a missing table entry is reported instead of being replaced with a plausible but different calendar.

Use Umm al-Qura when you need Taqwim’s established default behaviour or when the date must match the supplied Umm al-Qura data. Existing code that does not pass calendarSystem continues to use it.

Islamic Civil

Islamic Civil is a tabular calendar. Months 1, 3, 5, 7, 9 and 11 have 30 days; the alternating months have 29. Month 12 has 30 days in leap years 2, 5, 7, 10, 13, 16, 18, 21, 24, 26 and 29 of each 30-year cycle.

Because these rules are arithmetic, Taqwim can calculate backward and forward without a finite calendar table. The system uses the Friday epoch: 1 Muharram 1 AH corresponds to 19 July 622 in the proleptic Gregorian calendar.

Use it when a deterministic proleptic calendar is more important than matching Umm al-Qura data, or when another system explicitly uses the islamic-civil identifier.

Islamic TBLA

Islamic TBLA uses exactly the same month lengths and 30-year leap cycle as Islamic Civil. Its epoch is Thursday instead of Friday: 1 Muharram 1 AH corresponds to 18 July 622 in the proleptic Gregorian calendar.

That one-day epoch difference remains throughout the calendar. For the same Hijri fields, TBLA identifies the Gregorian day immediately before Civil. Use TBLA only when your data or integration specifically expects islamic-tbla; it is not an interchangeable spelling of Islamic Civil.

These are not moon-sighting calendars

None of these three choices represents a local observation of the crescent. Observed religious dates can vary by place and authority. Taqwim also does not expose the generic islamic identifier or Saudi sighting-based islamic-rgsa, because neither can be safely approximated by silently choosing one of these algorithms.

The identifiers follow the calendar names defined by Unicode CLDR. Taqwim performs its own deterministic conversion; it does not delegate Hijri conversion to the host’s Intl implementation.

Select a system in @taqwim/core

Umm al-Qura is exported from the main entry and selected automatically. Civil and TBLA use explicit subpath imports so they stay out of the default bundle.

import { islamicUmmAlQura, toHijri } from '@taqwim/core'
import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
import { islamicTbla } from '@taqwim/core/calendars/islamic-tbla'

toHijri('2026-08-30')
// Umm al-Qura, because calendarSystem is omitted

toHijri('2026-08-30', { calendarSystem: islamicCivil })
toHijri('2026-08-30', { calendarSystem: islamicTbla })
toHijri('2026-08-30', { calendarSystem: islamicUmmAlQura })

The same final { calendarSystem } option is available on calendar-dependent conversion, validation, month-length, weekday, arithmetic, business-day and formatting helpers.

Select a system in a calendar or date picker

Add @taqwim/core as a direct dependency when your application imports an optional strategy:

pnpm add @taqwim/core@beta

Every headless and styled calendar and date picker accepts the same calendarSystem option.

Vue

<script setup lang="ts">
import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
import { HijriCalendar } from '@taqwim/vue-styled'
</script>

<template>
  <HijriCalendar :calendar-system="islamicCivil" />
</template>

React

import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
import { HijriCalendar } from '@taqwim/react-styled'

export function Example() {
  return <HijriCalendar calendarSystem={islamicCivil} />
}

Svelte

<script lang="ts">
  import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
  import { HijriCalendar } from '@taqwim/svelte-styled'
</script>

<HijriCalendar calendarSystem={islamicCivil} />

Solid

import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
import { HijriCalendar } from '@taqwim/solid-styled'

export function Example() {
  return <HijriCalendar calendarSystem={islamicCivil} />
}

Angular

import { islamicCivil } from '@taqwim/core/calendars/islamic-civil'
import { HijriCalendar } from '@taqwim/angular-styled'
import { Component } from '@angular/core'

@Component({
  imports: [HijriCalendar],
  template: `<taqwim-hijri-calendar [calendarSystem]="calendarSystem" />`,
})
export class Example {
  readonly calendarSystem = islamicCivil
}

The active strategy controls conversion, headings, grid dates, navigation, validation, selection and Gregorian secondary dates. You can replace the prop at runtime; the calendar rebuilds its derived state without emitting a new selection.

Store dates without losing their meaning

The object { hy: 1448, hm: 3, hd: 10 } does not identify an absolute day by itself. If the Hijri fields are your stored record, persist the system too:

{
  date: { hy: 1448, hm: 3, hd: 10 },
  calendarSystem: 'islamic-civil',
}

For an appointment or another absolute event, prefer storing a canonical ISO Gregorian date and derive the chosen Hijri representation for display.

When a controlled calendar switches systems, Taqwim does not rewrite its numeric value. A date valid under one system can be invalid under another when their month lengths differ, so validate stored fields with the same strategy that created them.

Compatibility checklist

• Omitting calendarSystem always means Umm al-Qura, preserving existing calls and component markup.
• MIN_HIJRI_YEAR, MAX_HIJRI_YEAR and the documented 1343–1500 AH range describe the default Umm al-Qura table, not the proleptic calendars.
• Import Civil and TBLA from their explicit subpaths. This keeps optional algorithms out of applications that only use the default.
• Do not exchange bare Hijri fields with another service unless both sides agree on the calendar identifier.
• Do not use any deterministic result as a substitute for a local religious announcement based on observation.