luxon-hijri
Hijri calendar support for Luxon. Convert between Hijri and Gregorian, format dates in Arabic or English, and work with Hijri months in Luxon's DateTime API.
Overview
luxon-hijri wraps hijri-core with a Luxon-compatible API, adding formatting, locale support, and integration with Luxon's Duration and Interval types.
- Convert any Luxon
DateTimeto Hijri - Format Hijri dates with
iFormatpatterns - Locale-aware month and day names (Arabic, English, more)
- Built on
hijri-core(supports Umm al-Qura and FCNA systems) - Peer dependency:
luxon ^3.0.0
GitHub: github.com/acamarata/luxon-hijri
Installation
<span><span style="color: var(--shiki-token-function)">pnpm</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">add</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">luxon-hijri</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string)">luxon</span></span>
<span></span>API
toHijri
toHijri(dt: DateTime, system?: HijriSystem): HijriDate — converts a Luxon DateTime to Hijri.
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { toHijri } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon-hijri'</span></span>
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { DateTime } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon'</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">const</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">dt</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">DateTime</span><span style="color: var(--shiki-token-function)">.fromISO</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-string-expression)">'2025-03-29'</span><span style="color: var(--shiki-color-text)">)</span></span>
<span><span style="color: var(--shiki-token-keyword)">const</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">hijri</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">toHijri</span><span style="color: var(--shiki-color-text)">(dt)</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(hijri)</span></span>
<span><span style="color: var(--shiki-token-comment)">// { year: 1446, month: 9, day: 29, monthName: 'Ramadan', system: 'ummAlQura' }</span></span>
<span></span>toGregorian
toGregorian(hijri: HijriDate): DateTime — converts a Hijri date to a Luxon DateTime.
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { toGregorian } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon-hijri'</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">const</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">dt</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-function)">toGregorian</span><span style="color: var(--shiki-color-text)">({ year</span><span style="color: var(--shiki-token-keyword)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">1446</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> month</span><span style="color: var(--shiki-token-keyword)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">10</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> day</span><span style="color: var(--shiki-token-keyword)">:</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">1</span><span style="color: var(--shiki-color-text)"> })</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-constant)">dt</span><span style="color: var(--shiki-token-function)">.toISODate</span><span style="color: var(--shiki-color-text)">()) </span><span style="color: var(--shiki-token-comment)">// "2025-03-30"</span></span>
<span></span>formatHijriDate
formatHijriDate(dt: DateTime, fmt: string, locale?: string): string — formats a date using Hijri format tokens.
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { formatHijriDate } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon-hijri'</span></span>
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { DateTime } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon'</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">const</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">dt</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">DateTime</span><span style="color: var(--shiki-token-function)">.fromISO</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-string-expression)">'2025-03-29'</span><span style="color: var(--shiki-color-text)">)</span></span>
<span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'iD iMMMM iYYYY'</span><span style="color: var(--shiki-color-text)">)) </span><span style="color: var(--shiki-token-comment)">// "29 Ramadan 1446"</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'iD iMMMM iYYYY'</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'ar'</span><span style="color: var(--shiki-color-text)">)) </span><span style="color: var(--shiki-token-comment)">// "٢٩ رمضان ١٤٤٦"</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'ioooo/iMM/iDD'</span><span style="color: var(--shiki-color-text)">)) </span><span style="color: var(--shiki-token-comment)">// "1446/09/29"</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'iEEEE, iD iMMMM iYYYY'</span><span style="color: var(--shiki-color-text)">)) </span><span style="color: var(--shiki-token-comment)">// "Saturday, 29 Ramadan 1446"</span></span>
<span></span>Format patterns
All Hijri format tokens are prefixed with i to distinguish from Gregorian tokens.
| Token | Description | Example |
|---|---|---|
iD | Day of month, 1–30 | 29 |
iDD | Day of month, zero-padded | 29 |
iM | Month number, 1–12 | 9 |
iMM | Month number, zero-padded | 09 |
iMMM | Abbreviated month name | Ram. |
iMMMM | Full month name | Ramadan |
iooo | Hijri year (3 digits) | 446 |
ioooo | Hijri year (4 digits) | 1446 |
iYYYY | Hijri year (4 digits, same as ioooo) | 1446 |
iEEEE | Day of week (full) | Saturday |
iEEE | Day of week (abbreviated) | Sat |
Standard Luxon tokens (non-prefixed) still work and produce Gregorian output, so you can mix them: formatHijriDate(dt, 'iD iMMMM iYYYY (yyyy-MM-dd)') produces "29 Ramadan 1446 (2025-03-29)".
Locale support
Month and day names are available in multiple locales:
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { formatHijriDate } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon-hijri'</span></span>
<span><span style="color: var(--shiki-token-keyword)">import</span><span style="color: var(--shiki-color-text)"> { DateTime } </span><span style="color: var(--shiki-token-keyword)">from</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'luxon'</span></span>
<span></span>
<span><span style="color: var(--shiki-token-keyword)">const</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">dt</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-keyword)">=</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-constant)">DateTime</span><span style="color: var(--shiki-token-function)">.fromISO</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-string-expression)">'2025-03-29'</span><span style="color: var(--shiki-color-text)">)</span></span>
<span></span>
<span><span style="color: var(--shiki-token-comment)">// Arabic</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'iEEEE iD iMMMM iYYYY'</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'ar'</span><span style="color: var(--shiki-color-text)">))</span></span>
<span><span style="color: var(--shiki-token-comment)">// "السبت ٢٩ رمضان ١٤٤٦"</span></span>
<span></span>
<span><span style="color: var(--shiki-token-comment)">// Urdu</span></span>
<span><span style="color: var(--shiki-token-constant)">console</span><span style="color: var(--shiki-token-function)">.log</span><span style="color: var(--shiki-color-text)">(</span><span style="color: var(--shiki-token-function)">formatHijriDate</span><span style="color: var(--shiki-color-text)">(dt</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'iD iMMMM iYYYY'</span><span style="color: var(--shiki-token-punctuation)">,</span><span style="color: var(--shiki-color-text)"> </span><span style="color: var(--shiki-token-string-expression)">'ur'</span><span style="color: var(--shiki-color-text)">))</span></span>
<span><span style="color: var(--shiki-token-comment)">// "٢٩ رمضان ١٤٤٦"</span></span>
<span></span>Supported locales: en, ar, ur, tr, id, ms, fr. Additional locales can be registered via registerLocale().