jalali-js

English

فارسی

English

فارسی

Appearance

Documentation / jalali-js

jalali-js ​

npm versionBundle sizeLicense: MITDocs

Jalali (Persian, Shamsi) to Gregorian conversion core. TypeScript-native, zero runtime dependencies, framework-agnostic.

Start here: Live demo · Documentation

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

Contents ​

Install ​

sh
npm install jalali-js

Compatibility ​

ItemSupport
RuntimeModern Node and browsers
Node22 and 24 (CI matrix)
TypeScriptFirst-class types, no @types package
DependenciesNone at runtime
FrameworksNone required. Bindings are separate packages

Quick start ​

ts
import { createCalendar, toGregorian, fromGregorian } from 'jalali-js';

const jalali = createCalendar({ system: 'jalali' });
jalali.today(); // { year, month, day }

toGregorian({ year: 1403, month: 5, day: 15 }, 'jalali');
// { year: 2024, month: 8, day: 5 }

fromGregorian({ year: 2024, month: 8, day: 5 }, 'jalali');
// { year: 1403, month: 5, day: 15 }

API ​

Conversion and factory ​

  • createCalendar({ system, precision?, timeZone?, valueFormat?, engine? })
  • toGregorian(date, system, options?) / fromGregorian(date, system, options?)
  • engine: 'astronomical' opts into Tehran-meridian Nowruz (Meeus). Arithmetic is the default.

Date math and queries ​

addDays, addMonths, addYears, diffDates, startOf, endOf, isBefore, isAfter, isSameDay, isBetween, isToday, dayOfWeek.

Grid, selection, storage, time ​

  • buildCalendarGrid, nextMonth, previousMonth
  • SelectionRules, isDateSelectable, isRangeSelectable
  • toStorageValue and valueFormat (gregorian-iso default, plus date, epoch, Jalali shapes)
  • Time helpers: listHours, listMinutes, withTime
  • Event layout helpers: layoutMonthEvents, layoutWeekEvents, layoutDayTimedEvents

Full signatures: API reference.

Options ​

OptionValues (main)DefaultNotes
system'jalali' | 'gregorian'requiredDisplay / conversion calendar
precision'date' | 'datetime' | 'zoned-datetime''date'Matching TC39 Temporal-style tiers
valueFormat'gregorian-iso' | 'date' | 'epoch' | …'gregorian-iso'Shape of stored values from pickers
engine'arithmetic' | 'astronomical''arithmetic'Leap and Nowruz rule
timeZoneIANA id or 'auto'-For zoned-datetime ('auto' is SSR-safe)

Display stays Jalali when you ask for it. Storage stays Gregorian by default, like <input type="date">.

Theming ​

This package has no UI. Theme pickers through CSS variables in @jalali-js/react, @jalali-js/vue, or @jalali-js/web.

License ​

MIT

Interfaces ​

Type Aliases ​

Variables ​

Functions ​