# moment-jalaali

> Jalaali (Jalali, Persian, Khorshidi, Shamsi) calendar system plugin for moment.js.

Latest version **0.10.5** (published 2026-08-09) · MIT license · 25.7K weekly downloads

## Install

```sh
npm install moment-jalaali
pnpm add moment-jalaali
yarn add moment-jalaali
bun add moment-jalaali
```

## Health

**Score 73/100 (B)** — status: active.

Positive: has types package; no vulnerabilities; has provenance; recently updated; high quality score.

Warnings: no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.10.5 |
| Published | 2026-08-09 |
| First published | 2013-08-25 |
| Weekly downloads | 25.7K |
| License | MIT |
| TypeScript types | separate (@types/moment-jalaali) |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 128.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 976 |
| Author | Behrang Noruzi Niya |
| Maintainers | behrang, alitaheri |
| Keywords | jalaali, jalali, persian, khorshidi, shamsi, date, calendar, conversion, convert |

## Links

- npm: https://www.npmjs.com/package/moment-jalaali
- Repository: https://github.com/jalaali/moment-jalaali
- Issues: https://github.com/jalaali/moment-jalaali/issues
- npm.io page: https://npm.io/package/moment-jalaali

## Dependencies (3)

- [moment](https://npm.io/package/moment.md) ^2.30.1
- [jalaali-js](https://npm.io/package/jalaali-js.md) ^1.2.8
- [moment-timezone](https://npm.io/package/moment-timezone.md) ^0.6.2

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 0.10.5 (latest) — 2026-08-09
- 0.10.4 — 2024-11-09
- 0.10.3 — 2024-11-09
- 0.10.2 — 2024-11-09
- 0.10.1 — 2024-06-17
- 0.10.0 — 2023-04-15
- 0.9.6 — 2022-04-09
- 0.9.5 — 2022-04-09
- 0.9.4 — 2021-11-29
- 0.9.3 — 2021-11-29
- 0.9.2 — 2020-03-14
- 0.9.1 — 2019-10-07
- 0.9.0 — 2019-10-07
- 0.8.3 — 2018-12-01
- 0.8.2 — 2018-12-01
- … 29 more at https://npm.io/package/moment-jalaali/versions

## README

# moment-jalaali

A Jalaali (Jalali, Persian, Khorshidi, Shamsi) calendar system plugin for moment.js.

[![NPM](https://img.shields.io/npm/v/moment-jalaali.svg)](https://www.npmjs.com/package/moment-jalaali)
[![Build Status](https://travis-ci.org/jalaali/moment-jalaali.png?branch=master)](https://travis-ci.org/jalaali/moment-jalaali)

Jalali calendar is a solar calendar that was used in Persia, variants of which today are still in use in Iran as well as Afghanistan. [Read more on Wikipedia](http://en.wikipedia.org/wiki/Jalali_calendar) or see [Calendar Converter](http://www.fourmilab.ch/documents/calendar/).

This plugin adds Jalaali calendar support to [momentjs](http://momentjs.com) library.

Calendar conversion is based on the [algorithm provided by Kazimierz M. Borkowski](http://www.astro.uni.torun.pl/~kb/Papers/EMP/PersianC-EMP.htm) and has a very good performance.

## Note (Feb 2022)

If you just need to display date and time in Persian calendar, you may use `Intl` which is ECMAScript Internationalization API with a [very good browser support](https://caniuse.com/mdn-javascript_builtins_intl_datetimeformat_format). For example:

```js
const d = new Date(2022,2,21)

// Simple format
console.log(new Intl.DateTimeFormat('fa-IR').format(d));
// => ۱۴۰۱/۱/۱

// Full long format
console.log(new Intl.DateTimeFormat('fa-IR', {dateStyle: 'full', timeStyle: 'long'}).format(d));
// => ۱۴۰۱ فروردین ۱, دوشنبه، ساعت ۰:۰۰:۰۰ (‎+۳:۳۰ گرینویچ)

// Latin numbers
console.log(new Intl.DateTimeFormat('fa-IR-u-nu-latn', {dateStyle: 'full', timeStyle: 'long'}).format(d));
// => 1401 فروردین 1, دوشنبه، ساعت 0:00:00 (‎+3:30 گرینویچ)

// English US locale with Persian calendar
console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {dateStyle: 'full', timeStyle: 'long'}).format(d));
// => Monday, Farvardin 1, 1401 AP at 12:00:00 AM GMT+3:30

// Just year
console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {year: 'numeric'}).format(d));
// => 1401 AP

// Just month
console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {month: 'short'}).format(d));
// Farvardin

// Just day
console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {day: 'numeric'}).format(d));
// => 1
```

## Where to use it

Like `momentjs`, `moment-jalaali` works in browser and in Node.js.

### Node.js

```shell
npm install moment-jalaali
```

```js
var moment = require('moment-jalaali')
moment().format('jYYYY/jM/jD')
```

### Browser

You may use the `node_modules/build/moment-jalaali.js` file.

```html
<script src="node_modules/moment/min/moment.min.js"></script>
<script src="node_modules/moment-jalaali/build/moment-jalaali.js"></script>
<script>
  moment().format('jYYYY/jM/jD')
</script>
```

## Typescript

If you need type definitions for typescript, you need to install them separately.

```shell
npm install @types/moment-jalaali
```

## API

This plugin tries to mimic `momentjs` api. Basically, when you want to format or parse a string, just add a `j` to the format token like 'jYYYY' or 'jM'. For example:

```js
m = moment('1360/5/26', 'jYYYY/jM/jD') // Parse a Jalaali date
m.format('jYYYY/jM/jD [is] YYYY/M/D') // 1360/5/26 is 1981/8/17

m.jYear() // 1360
m.jMonth() // 4
m.jDate() // 26
m.jDayOfYear() // 150
m.jWeek() // 22
m.jWeekYear() // 1360

m.add(1, 'jYear')
m.add(2, 'jMonth')
m.add(3, 'day')
m.format('jYYYY/jM/jD') // 1361/7/29

m.jMonth(11)
m.startOf('jMonth')
m.format('jYYYY/jM/jD') // 1361/12/1

m.jYear(1392)
m.startOf('jYear')
m.format('jYYYY/jM/jD') // 1392/1/1

m.subtract(1, 'jYear')
m.subtract(1, 'jMonth')
m.format('jYYYY/jM/jD') // 1390/12/1

moment('1391/12/30', 'jYYYY/jMM/jDD').isValid() // true (leap year)
moment('1392/12/30', 'jYYYY/jMM/jDD').isValid() // false (common year)
moment.jIsLeapYear(1391) // true
moment.jIsLeapYear(1392) // false

moment.jDaysInMonth(1395, 11) // 30
moment.jDaysInMonth(1394, 11) // 29

moment('1392/6/3 16:40', 'jYYYY/jM/jD HH:mm').format('YYYY-M-D HH:mm:ss') // 2013-8-25 16:40:00

moment('2013-8-25 16:40:00', 'YYYY-M-D HH:mm:ss').endOf('jMonth').format('jYYYY/jM/jD HH:mm:ss') // 1392/6/31 23:59:59

// Complex parse:
moment('1981 5 17', 'YYYY jM D').format('YYYY/MM/DD') // 1981/07/17
```

To add Persian language, use loadPersian method:

```js
moment.loadPersian([options])
```

### Options

| Param            | Type    | Default   | Description                               | Example                                      |
| ---------------- | ------- | -------   | ----------------------------------------  | -------------------------------------------- |
| usePersianDigits | Boolean | `false`   | Use persian digits (Use at your own risk) | `moment.loadPersian({usePersianDigits: true})` |
| dialect *        | String  | `persian` | Available values = `persian`, `persian-modern` | `moment.loadPersian({dialect: 'persian-modern'})` |

*use dialect option to change `usePersian` dialect, available options are:

* persian: default dialect(امرداد، آدینه، ...)

* persian-modern: modern dialect(مرداد، جمعه، ...)

#### in case getting error `'humanize' of undefined`

you should also require locale fa

```js
require('moment/locale/fa')
```

### React Native

To use `fromNow()` in React Native projects:

```js
import moment from "moment-jalaali";
import fa from "moment/src/locale/fa";
moment.locale("fa", fa);
moment.loadPersian();
```

## Related Projects

### react-datepicker2

A simple and reusable Datepicker component for React (with persian jalali calendar support) [Demo](https://mberneti.github.io/react-datepicker2/).
created by [@mberneti](https://github.com/mberneti).

### react-advance-jalaali-datepicker

A React module, which provides different jalaali (persian) datepicker types such as, range date and time picker, developed base on `moment-jalaali`. [react-advance-jalaali-datepicker](https://github.com/A-Kasaaian/react-advance-jalaali-datepicker) created by [@A-Kasaaian](https://github.com/A-Kasaaian).

### ng-persian-datepicker

[ng-persian-datepicker](https://github.com/Saeed-Pooyanfar/ng-persian-datepicker) is an angular 8+ date-time picker component for shamsi calendar system with some useful customization settings.

### ng-jalali-flat-datepicker

A lightweight angular.js date picker using `moment-jalaali` is [thg303/ng-jalali-flat-datepicker](https://github.com/thg303/ng-jalali-flat-datepicker) created by [@thg303](https://github.com/thg303).

### pholiday

A library based on `moment-jalaali` for calculating holidays in Persian calendar is [shkarimpour/pholiday](https://github.com/shkarimpour/pholiday) created by [@shkarimpour](https://github.com/shkarimpour).

### moment-hijri

Another calendar system plugin for `momentjs` is [moment-hijri](https://github.com/xsoh/moment-hijri) created by [@xsoh](https://github.com/xsoh).

### vue-persian-datetime-picker

[vue-persian-datetime-picker](https://github.com/talkhabi/vue-persian-datetime-picker) is a `vuejs` plugin to select jalali date and time, created by [@talkhabi](https://github.com/talkhabi).

### react-native-general-calendars

[react-native-general-calendars](https://github.com/rghorbani/react-native-general-calendars) is a `react-native` component with support of gregorian, jalaali and hijri calendar to selectand work with date and time, created by [@rghorbani](https://github.com/rghorbani).

### imrc-datetime-picker

[imrc-datetime-picker](https://github.com/smrsan76/imrc-datetime-picker) is a `react` component with support of gregorian and jalaali calendar in both english and persian (modern) languages to select and work with date and time, created by [@smrsan76](https://github.com/smrsan76).

## License

MIT

---
_Source: https://npm.io/package/moment-jalaali · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._