Gotchas

Details that surprise people the first time.

The Gregorian identifier is gregory

@internationalized/date reports a Gregorian CalendarDate with calendar.identifier === 'gregory', while this package names the calendar gregorian.

toString() prints the Gregorian date

CalendarDate#toString() always prints the Gregorian ISO date, even for an Umm al-Qura date. Read year, month, and day to get the Hijri numbers, or use the adapter's toIso8601.

0-based and 1-based months

Material adapter months are 0-based: createDate(1445, 8, 1) is 1 Ramadan. The calendar helpers are 1-based: createCalendarDate('islamic-umalqura', 1445, 9, 1) is the same day.

Invalid dates throw

Formatting or converting an invalid date throws, and so does creating a date outside AH 1300–1599. Parsing typed text does not throw: unreadable or out-of-range text returns an invalid date instead.

Locale never picks the calendar

ar-SA does not select the Hijri calendar and en-US does not select Gregorian. Always set calendar or valueCalendar explicitly when the default is not what you want.