jalali-jsA TypeScript-native Jalali calendar library

Display Jalali (Persian, Shamsi) dates. Store Gregorian, by default, without extra thought.

Display Jalali, store Gregorian

Every component and every core conversion function returns a Gregorian, calendar-agnostic value by default, the same contract a native follows. Opt into a Jalali-native stored value with one option, when you actually need one.

Precision tiers, not optional fields

CalendarDate, CalendarDateTime, and ZonedCalendarDateTime are three separate types, matching TC39 Temporal's own tiers, so code written against a plain date can never accidentally read a time field that was never set.

React, Vue, or no framework at all

Headless primitives (data attributes, scoped slots) for full control, plus a working default-styled DatePicker for zero-setup use. @jalali-js/web ships the same components as plain Web Components, so a page with no framework, or one this project has no dedicated binding for, gets the exact same picker and theme CSS.

Built on a validated arithmetic engine

The Jalali leap-year rule is checked against Node's own ICU Persian calendar with zero mismatches across a multi-thousand-year range, plus an independent, published reference table.

Start here

npm ecosystem

jalali-js · @jalali-js/i18n · @jalali-js/nlp · @jalali-js/holidays · @jalali-js/react · @jalali-js/vue · @jalali-js/web · @jalali-js/ui-react · @jalali-js/ui-vue · @jalali-js/ui-web

Package	Role
`jalali-js`	Conversion core
`@jalali-js/i18n`	Locales and formatting
`@jalali-js/nlp`	Natural language parsing
`@jalali-js/holidays`	Iran holidays
`@jalali-js/react`	React bindings
`@jalali-js/vue`	Vue bindings
`@jalali-js/web`	Web Components
`@jalali-js/ui-react`	React UI (range, events)
`@jalali-js/ui-vue`	Vue UI
`@jalali-js/ui-web`	Web Components UI