react-jalali-calendar

react-jalali-calendar

Persian (Jalali / Shamsi) calendar components and date utilities for React.
Built on jalaali-js with no UI framework dependency.

فارسی

---

Table of contents

• Installation
• Quick start
• Components
  • JalaliCalendar
  • JalaliDatePicker
• Headless hook
• Core utilities
• Theming
• TypeScript types
• Week convention

---

Installation

npm install react-jalali-calendar
# or
pnpm add react-jalali-calendar
# or
yarn add react-jalali-calendar

Peer dependencies (must already be in your project):

npm install react react-dom   # 18 or 19

---

Quick start

import { useState } from "react";
import { JalaliCalendar, JalaliDatePicker } from "react-jalali-calendar";
import "react-jalali-calendar/styles.css";

export function BookingForm() {
  const [date, setDate] = useState("");           // "YYYY-MM-DD" string
  const [selected, setSelected] = useState<Date | null>(null);

  return (
    <div>
      {/* Inline calendar */}
      <JalaliCalendar
        selectedDate={selected}
        onSelectDate={setSelected}
        latinDigits={false}
      />

      {/* Popup date picker */}
      <JalaliDatePicker value={date} onChange={setDate} />
    </div>
  );
}

Import styles.css once in your app entry point (e.g. main.tsx or layout.tsx).

---

Components

JalaliCalendar

An inline month grid. The component manages its own navigation state internally; you only control which day is selected.

import { JalaliCalendar } from "react-jalali-calendar";

<JalaliCalendar
  selectedDate={selected}
  onSelectDate={(date) => setSelected(date)}
/>

Props

Prop	Type	Default	Description
selectedDate	Date | null	required	The currently selected date. Pass null for no selection.
onSelectDate	(date: Date) => void	required	Called with the Date object when the user clicks a day.
isDateDisabled	(date: Date) => boolean	—	Return true to make a day unclickable.
latinDigits	boolean	false	Show digits as 0-9 instead of ۰-۹.
initialMonth	{ jy: number; jm: number }	current month	Jalali year/month shown on first render.
prevMonthLabel	string	"ماه قبل"	aria-label for the previous-month button.
nextMonthLabel	string	"ماه بعد"	aria-label for the next-month button.
className	string	—	Extra CSS class added to the root <div>.

Examples

// Disable all days in the past
<JalaliCalendar
  selectedDate={selected}
  onSelectDate={setSelected}
  isDateDisabled={(date) => date < new Date()}
/>

// Open on a specific month (Farvardin 1403)
<JalaliCalendar
  selectedDate={null}
  onSelectDate={setSelected}
  initialMonth={{ jy: 1403, jm: 1 }}
/>

// Latin digits + custom class
<JalaliCalendar
  selectedDate={selected}
  onSelectDate={setSelected}
  latinDigits
  className="my-calendar"
/>

---

JalaliDatePicker

A button that opens a popover containing JalaliCalendar. Closes on outside click or Escape. The selected date is stored as a "YYYY-MM-DD" string (Gregorian local date key), which is easy to send to a server or store in a form.

import { JalaliDatePicker } from "react-jalali-calendar";

const [date, setDate] = useState(""); // e.g. "2024-03-20"

<JalaliDatePicker value={date} onChange={setDate} />

Props

Prop	Type	Default	Description
value	string	required	A YYYY-MM-DD Gregorian date key, or "" for no selection.
onChange	(value: string) => void	required	Called with the new YYYY-MM-DD string when a day is picked.
placeholder	string	"انتخاب تاریخ"	Text shown on the trigger button when no date is selected.
latinDigits	boolean	false	Display the selected date label with Latin digits.
isDateDisabled	(date: Date) => boolean	—	Passed through to the inner JalaliCalendar.
className	string	—	Extra class on the picker root element.
calendarClassName	string	—	Extra class on the inner JalaliCalendar.

Examples

// Disable weekends (Friday = index 5 in JS Date)
<JalaliDatePicker
  value={date}
  onChange={setDate}
  isDateDisabled={(d) => d.getDay() === 5}
  latinDigits
/>

// With a custom placeholder
<JalaliDatePicker
  value={date}
  onChange={setDate}
  placeholder="تاریخ تولد را انتخاب کنید"
/>

---

Headless hook

Use useJalaliCalendar to build a completely custom calendar UI while letting the library handle month navigation and grid generation.

import { useJalaliCalendar } from "react-jalali-calendar";
import { PERSIAN_MONTHS, PERSIAN_WEEKDAYS_SHORT, localDateKey } from "react-jalali-calendar/core";

function MyCalendar({ selectedDate, onSelectDate }) {
  const { jy, jm, grid, today, todayKey, prevMonth, nextMonth, goToMonth, goToToday } =
    useJalaliCalendar({ initialMonth: { jy: 1403, jm: 6 } });

  return (
    <div dir="rtl">
      <div>
        <button onClick={prevMonth}>قبل</button>
        <strong>{PERSIAN_MONTHS[jm - 1]} {jy}</strong>
        <button onClick={nextMonth}>بعد</button>
        <button onClick={goToToday}>امروز</button>
      </div>

      <div style={{ display: "grid", gridTemplateColumns: "repeat(7, 1fr)" }}>
        {PERSIAN_WEEKDAYS_SHORT.map((d) => (
          <span key={d}>{d}</span>
        ))}

        {grid.map((date, i) => {
          if (!date) return <span key={i} />;
          const key = localDateKey(date);
          return (
            <button
              key={key}
              onClick={() => onSelectDate(date)}
              style={{ fontWeight: key === todayKey ? "bold" : undefined }}
            >
              {date.getDate()}
            </button>
          );
        })}
      </div>
    </div>
  );
}

Return value

Property	Type	Description
jy	number	Currently displayed Jalali year.
jm	number	Currently displayed Jalali month (1-12).
grid	(Date | null)[]	Flat array of day cells. null entries are leading empty cells before the 1st of the month.
today	JalaliDateParts	Today's { jy, jm, jd }.
todayKey	string	Today as "YYYY-MM-DD", useful for highlighting.
prevMonth	() => void	Navigate one month back.
nextMonth	() => void	Navigate one month forward.
goToMonth	(jy, jm) => void	Jump to any Jalali year/month directly.
goToToday	() => void	Jump back to the current month.

Options

useJalaliCalendar({
  initialMonth: { jy: 1403, jm: 1 }, // optional, defaults to current month
})

---

Core utilities

Import pure date helpers from the /core sub-path. This entry point has no React dependency and can be used in Node.js, server components, or non-React projects.

import {
  toJalali,
  fromJalali,
  formatJalali,
  formatTime,
  getJalaliMonthGrid,
  getJalaliWeekDates,
  addJalaliMonths,
  monthDateRange,
  localDateKey,
  isoDateOnly,
  toLatinDigits,
  toPersianDigits,
  PERSIAN_MONTHS,
  PERSIAN_WEEKDAYS,
  PERSIAN_WEEKDAYS_SHORT,
} from "react-jalali-calendar/core";

Conversion

toJalali(date: Date): JalaliDateParts

Convert a Date object to Jalali parts.

toJalali(new Date("2024-03-20"));
// => { jy: 1403, jm: 1, jd: 1 }

fromJalali(parts: JalaliDateParts): Date

Convert Jalali { jy, jm, jd } back to a Gregorian Date.

fromJalali({ jy: 1403, jm: 1, jd: 1 });
// => Date("2024-03-20")

Formatting

formatJalali(date, options?): string

Human-readable Jalali date string.

formatJalali(new Date("2024-03-20"));
// => "۱ فروردین ۱۴۰۳"

formatJalali(new Date("2024-03-20"), { includeWeekday: true });
// => "چهارشنبه، ۱ فروردین ۱۴۰۳"

formatJalali(new Date("2024-03-20"), { latinDigits: true });
// => "1 فروردین 1403"

Option	Type	Default	Description
includeWeekday	boolean	false	Prepend the Persian weekday name.
latinDigits	boolean	false	Use 0-9 instead of ۰-۹.

formatTime(date: Date, latinDigits?: boolean): string

Format hours and minutes as HH:MM.

formatTime(new Date(), true);   // "09:45"
formatTime(new Date(), false);  // "۰۹:۴۵"

toPersianDigits(value: string): string

Replace 0-9 with ۰-۹ anywhere in a string.

toPersianDigits("1403/01/01"); // "۱۴۰۳/۰۱/۰۱"

toLatinDigits(value: string): string

Replace ۰-۹ with 0-9 anywhere in a string.

toLatinDigits("۱۴۰۳"); // "1403"

Date keys

localDateKey(date: Date): string

Returns a "YYYY-MM-DD" string using local time (no UTC shift). This is the format used by JalaliDatePicker.

localDateKey(new Date("2024-03-20")); // "2024-03-20"

isoDateOnly(date: Date): string

Returns a "YYYY-MM-DD" string using UTC (date.toISOString().slice(0, 10)).

Grid helpers

getJalaliMonthGrid(jy: number, jm: number): (Date | null)[]

Returns a flat array of cells for a full month grid (Saturday-anchored). Leading cells before the 1st are null.

const cells = getJalaliMonthGrid(1403, 1);
// cells[0] might be null (padding), then Date objects for each day

getJalaliWeekDates(jy: number, jm: number, jd: number): Date[]

Returns the 7 Date objects for the Jalali week (Saturday to Friday) containing the given date.

getJalaliWeekDates(1403, 1, 10); // [Date(Sat), ..., Date(Fri)]

addJalaliMonths(jy: number, jm: number, delta: number): JalaliDateParts

Add or subtract months, handling year rollovers correctly.

addJalaliMonths(1403, 12, 1);  // => { jy: 1404, jm: 1, jd: 1 }
addJalaliMonths(1403, 1, -1);  // => { jy: 1402, jm: 12, jd: 1 }

monthDateRange(jy: number, jm: number): { from: Date; to: Date }

Returns the first and last Date of a Jalali month (last date is set to 23:59:59.999). Useful for API range queries.

const { from, to } = monthDateRange(1403, 1);
// from: 2024-03-20 00:00:00
// to:   2024-04-19 23:59:59.999

Constants

PERSIAN_MONTHS[0]         // "فروردین"  (index 0 = month 1)
PERSIAN_WEEKDAYS[0]       // "شنبه"     (index 0 = Saturday)
PERSIAN_WEEKDAYS_SHORT[0] // "ش"

---

Theming

The components use CSS custom properties scoped under the .rjc and .rjc-picker class names. Override any variable to match your design system.

/* globals.css or any stylesheet loaded after styles.css */
:root {
  --rjc-primary:     #7c3aed;
  --rjc-primary-fg:  #ffffff;
  --rjc-radius:      0.75rem;
  --rjc-font:        "Vazirmatn", sans-serif;
}

Or scope overrides to a specific instance:

.booking-calendar {
  --rjc-primary: #0ea5e9;
  --rjc-cell-size: 2.5rem;
}

<JalaliCalendar className="booking-calendar" ... />

All available variables

Variable	Controls
--rjc-bg	Calendar background
--rjc-fg	Text color
--rjc-muted	Weekday header text
--rjc-border	Border color
--rjc-primary	Selected day background
--rjc-primary-fg	Selected day text
--rjc-hover	Day hover background
--rjc-today-ring	Ring color on today's cell
--rjc-disabled	Disabled day text color
--rjc-radius	Border radius of cells and container
--rjc-cell-size	Width/height of each day cell
--rjc-cell-gap	Gap between cells in the grid
--rjc-font	Font family

---

TypeScript types

All public types are exported from the main entry point:

import type {
  JalaliDateParts,
  JalaliCalendarProps,
  JalaliDatePickerProps,
  UseJalaliCalendarOptions,
} from "react-jalali-calendar";

JalaliDateParts

type JalaliDateParts = {
  jy: number; // Jalali year
  jm: number; // Jalali month (1-12)
  jd: number; // Jalali day (1-29/30/31)
};

---

Week convention

This library treats Saturday as day 0 and Friday as day 6, which matches the Iranian week. The grid returned by getJalaliMonthGrid and useJalaliCalendar is aligned to this convention -- the first column is always Saturday.

Index	Day
0	شنبه (Saturday)
1	یکشنبه (Sunday)
2	دوشنبه (Monday)
3	سه‌شنبه (Tuesday)
4	چهارشنبه (Wednesday)
5	پنجشنبه (Thursday)
6	جمعه (Friday)

---

License

MIT - TronIsHere