multi-calendar-datepicker

Multi Calendar Datepicker

Lightweight, dependency-free datepicker supporting Gregorian (with Levantine month names), Hijri (official Umm al-Qura), Jalali (Persian), and Coptic calendars — with range selection, dual-calendar display, RTL, and full CSS-variable theming.

Why this library? Browser Intl Hijri data diverges from the official Saudi Umm al-Qura calendar in 61 of 180 months (2030–2044) — and varies by browser version. We embed the official table itself: 372/372 verified month starts, exact until 2077. Read the measurements →

منتقي تواريخ خفيف بدون أي اعتماديات يدعم التقويم الميلادي (بأسماء يناير أو كانون الثاني) والهجري (أم القرى الرسمي) والفارسي والقبطي — مع اختيار نطاق، وعرض تقويمَين معاً، ودعم RTL، وتخصيص كامل عبر متغيرات CSS.

Why this one? / لماذا هذه المكتبة؟

• Official Umm al-Qura accuracy — the Hijri calendar uses an embedded month-length table (AH 1318–1500 / 1900–2077 CE) generated from the official Saudi Umm al-Qura data (the same data behind .NET's UmAlQuraCalendar and the published KACST tables). Browser Intl CLDR data — which is consistently one day late vs. the official calendar — is only used as a fallback outside that range.
• دقة أم القرى الرسمية — جدول مضمّن من البيانات السعودية الرسمية، وليس بيانات المتصفح (CLDR) المتأخرة يوماً واحداً.
• Correct Jalali leap years via the jalaali-js breaks-table algorithm (1403 leap, 1404 not).
• Timezone-proof: all dates are plain {year, month, day} objects — no Date drift.

Install / التثبيت

<!-- CDN / plain script -->
<link rel="stylesheet" href="dist/multi-calendar-datepicker.css">
<script src="dist/multi-calendar-datepicker.js"></script>

// ESM
import MCD, { Datepicker } from 'multi-calendar-datepicker';
import 'multi-calendar-datepicker/css';

Quick start / البداية السريعة

<input id="date" placeholder="اختر التاريخ">
<input type="hidden" id="date_db">

const picker = new MultiCalendarDatepicker.Datepicker('#date', {
  calendar:     'hijri',
  hijriMode:    'ummalqura',   // official Saudi calendar
  locale:       'ar',
  dir:          'rtl',
  weekendDays:  [5, 6],        // Fri + Sat highlighted
  outputTarget: '#date_db',    // receives the Gregorian ISO value
});

picker.getGregorianValue();    // "2026-06-27"
picker.getDisplayValue();      // "1448-01-12"

Range selection / اختيار نطاق

new MultiCalendarDatepicker.Datepicker('#range', {
  calendar: 'hijri',
  hijriMode: 'ummalqura',
  mode: 'range',
});
// getGregorianValue() → "2026-06-16/2026-06-27"
// getResult() → { mode:'range', start, end, gregorianStart, gregorianEnd, ... }

Dual calendar / عرض تقويمَين

Show the Gregorian date in small type inside every Hijri day cell (like phone calendars):

new MultiCalendarDatepicker.Datepicker('#dual', {
  calendar: 'hijri',
  hijriMode: 'ummalqura',
  secondaryCalendar: 'gregorian',
});

React

import { MultiCalendarDatepicker } from 'multi-calendar-datepicker/react';
import 'multi-calendar-datepicker/css';

<MultiCalendarDatepicker
  options={{ calendar: 'hijri', hijriMode: 'ummalqura', locale: 'ar', dir: 'rtl' }}
  value={gregorianIso}
  onChange={detail => setGregorianIso(detail.value)}
  placeholder="اختر التاريخ"
/>

Or bring your own input with the hook:

const { inputRef, pickerRef } = useMultiCalendarDatepicker({ calendar: 'hijri', hijriMode: 'ummalqura' });
return <input ref={inputRef} />;

Options / الخيارات

Option	Default	Description
calendar	'gregorian'	'gregorian' | 'hijri' | 'jalali' | 'coptic'
hijriMode	'tabular'	'ummalqura' = official Saudi calendar
gregorianMonths	'default'	'levant' = كانون الثاني… (Iraq/Levant) | 'both'
hijriAdjust	0	±N-day shift for local moon-sighting differences
mode	'single'	'range' = from–to selection
secondaryCalendar	null	second calendar shown inside day cells
locale	'en'	'en' | 'ar' | 'fa'
dir	'ltr'	'rtl' for Arabic/Persian
digits	'latin'	'arabic' (١٢٣) | 'persian' (۱۲۳)
displayFormat	'YYYY-MM-DD'	display pattern
outputTarget	null	selector of input receiving Gregorian ISO
resultTarget / resultTemplate	—	render {{gregorian}}, {{display}}, {{gregorianStart}}, {{gregorianEnd}} …
weekStart	0	0=Sun … 6=Sat
weekendDays	[]	highlighted columns, e.g. [5,6]
minDate / maxDate / disabledDates / disabledWeekDays	—	constraints (Gregorian)
allowInput	false	type the date manually (validated on Enter/blur)
theme	'light'	'dark' | 'auto' | named theme | inline vars object
backgroundSvg	null	inline SVG as picker background

Events / الأحداث

input.addEventListener('mcd:change', e => {
  e.detail.value;          // Gregorian ISO ("s/e" in range mode)
  e.detail.displayValue;   // formatted in the active calendar
  e.detail.gregorianDate;  // {year, month, day}
});
// Also: mcd:init, mcd:open, mcd:close, mcd:clear, mcd:range-start

Keyboard / لوحة المفاتيح

Arrows move by day/week (RTL-aware, crosses months) · PageUp/PageDown month · Shift+PageUp/Down year · Home/End first/last day · Enter/Space select · Esc close.

Theming / التخصيص

Every visual property is a CSS variable (--mcd-*). Override globally on :root or per instance:

.my-picker { --mcd-primary: #0d9488; --mcd-radius: 16px; }

Longevity & self-renewal / التجدد الذاتي

The tool is designed to keep working without intervention:

Component	Valid until	Then
Gregorian	forever	—
Coptic (pure arithmetic)	forever	—
Jalali (breaks table)	SH 3177 (~3798 CE)	—
Umm al-Qura official table	AH 1500 (Nov 2077 CE)	automatic fallback → Intl CLDR astronomical simulation (to ~2174 CE) → tabular approximation
UI year list	self-renewing (computed −100/+50 around today)	—

بعد 2077 الأداة لا تنكسر — تنتقل تلقائياً لمحاكاة CLDR الفلكية. وعندما تنشر السعودية بيانات ما بعد 1500هـ، يكفي سطر واحد بدون تعديل المكتبة:

// Data generated with tools/generate-uq-table.ps1 from official sources
MultiCalendarDatepicker.extendUmmalquraData([0xABC, 0x5AD /* AH 1501, 1502, … */]);

MultiCalendarDatepicker.isOfficialUmmalquraYear(1501); // → true after extension

Build & test

npm install
npm run build   # dist/ (UMD + ESM + CSS) from src/
npm test        # vitest

License

MIT