Persian Date

A single set of date utilities that works across the Jalali (Solar Hijri) and Gregorian calendars: format and parse dates, convert between calendars, do calendar-aware arithmetic, and validate reservation-style ranges — all built on date-fns and date-fns-jalali.

Last updated August 12, 2026

Overview

Installation

$ npx shadcn@latest add https://ui.persian-labs.ir/r/persian-date.json

Usage

Every function that reads or manipulates calendar fields (months, years, week boundaries) accepts an optional calendarType — the Jalali calendar is the default, since this library is Iran-first.

import { formatDate, addDays, today } from "@/lib/persian-date"
 
const checkIn = today()
const checkOut = addDays(checkIn, 3)
 
formatDate(checkIn, "yyyy/MM/dd") // "1404/06/01" (Jalali by default)
formatDate(checkOut, "d MMMM", { calendarType: "miladi" }) // Gregorian

Examples

Parsing

parseDate normalizes Persian/Arabic-Indic digits before parsing, and returns null instead of an invalid Date on failure.

Shamsi ↔ Miladi conversion

toParts/fromParts (and their toShamsi/toMiladi/fromShamsi/fromMiladi shorthands) round-trip a Date through calendar fields without losing precision.

Calendar-aware arithmetic

addMonths and addYears respect the active calendar's month lengths — adding a month to the end of Esfand behaves differently than adding one to the Gregorian February.

Start / end of week, month, year

startOfWeek/endOfWeek default to a Saturday-start week for shamsi (Sunday for miladi); startOfMonth/endOfMonth and startOfYear/endOfYear follow the same calendar-aware pattern.

Leap year & days in month

isLeapYear and daysInMonth resolve Esfand's 29 vs. 30 days for the Jalali calendar.

Comparisons

isToday, isPast, and isFuture classify a date relative to the current moment.

Date range

eachDayOfRange lists every day in an inclusive range; isWithinRange checks whether a given date falls inside it.

Range validation (reservation form)

validateRange is built for hospital/hotel-style booking forms: it checks ordering, minimum/maximum stay length, past dates, and specific blocked dates, returning a machine-readable reason you can map to a message.

RTL

formatDate already outputs Persian digits and Persian month/weekday names by default in the shamsi calendar, so the formatted string reads naturally inside right-to-left content with no extra direction handling.

API Reference

Formatting & Parsing

Prop	Type	Default	Description
formatDate(date, pattern, options?)	(date: Date \| number, pattern: string, options?: DateOptions) => string	—	Formats a date using date-fns tokens (yyyy/MM/dd, EEEE d MMMM, ...), switching between the Jalali and Gregorian calendars via calendarType.
parseDate(value, pattern, referenceDate?, options?)	(value: string, pattern: string, referenceDate?: Date \| number, options?: DateOptions) => Date \| null	—	Parses a date string against a date-fns pattern. Normalizes Persian/Arabic-Indic digits before parsing. Returns null instead of an invalid Date on failure.
isValidDate(value)	(value: unknown) => value is Date	—	True if value is a valid, non-NaN Date.

Conversion

Prop	Type	Default	Description
toParts(date, calendarType?)	(date: Date, calendarType?: CalendarType) => DateParts	"shamsi"	Reads a date's calendar fields (1-indexed month) in the given calendar.
fromParts(parts, calendarType?)	(parts: DateParts, calendarType?: CalendarType) => Date	"shamsi"	Builds a Date (at local midnight) from calendar fields (1-indexed month).
toShamsi(date)	(date: Date) => DateParts	—	Shorthand for toParts(date, "shamsi").
toMiladi(date)	(date: Date) => DateParts	—	Shorthand for toParts(date, "miladi").
fromShamsi(parts)	(parts: DateParts) => Date	—	Shorthand for fromParts(parts, "shamsi").
fromMiladi(parts)	(parts: DateParts) => Date	—	Shorthand for fromParts(parts, "miladi").

Arithmetic

Prop	Type	Default	Description
today()	() => Date	—	Local midnight of the current date.
now()	() => Date	—	The current date and time.
addDays(date, amount)	(date: Date, amount: number) => Date	—	Adds calendar-independent days to date.
addWeeks(date, amount)	(date: Date, amount: number) => Date	—	Adds calendar-independent weeks to date.
addMonths(date, amount, calendarType?)	(date: Date, amount: number, calendarType?: CalendarType) => Date	"shamsi"	Adds months; month length is resolved in the given calendar.
addYears(date, amount, calendarType?)	(date: Date, amount: number, calendarType?: CalendarType) => Date	"shamsi"	Adds years; year length is resolved in the given calendar.
startOfDay(date) / endOfDay(date)	(date: Date) => Date	—	Local midnight, or the last instant of the day.
startOfWeek(date, calendarType?) / endOfWeek(date, calendarType?)	(date: Date, calendarType?: CalendarType) => Date	"shamsi"	Week starts on Saturday for shamsi, Sunday for miladi.
startOfMonth(date, calendarType?) / endOfMonth(date, calendarType?)	(date: Date, calendarType?: CalendarType) => Date	"shamsi"	First/last day of the month in the given calendar.
startOfYear(date, calendarType?) / endOfYear(date, calendarType?)	(date: Date, calendarType?: CalendarType) => Date	"shamsi"	First/last day of the year in the given calendar.
daysInMonth(date, calendarType?)	(date: Date, calendarType?: CalendarType) => number	"shamsi"	Number of days in date's month, in the given calendar.
isLeapYear(date, calendarType?)	(date: Date, calendarType?: CalendarType) => boolean	"shamsi"	True when date's year is a leap year in the given calendar.

Comparisons & Ranges

Prop	Type	Default	Description
daysBetween(from, to)	(from: Date, to: Date) => number	—	Real elapsed days between two dates, independent of calendar system.
monthsBetween(from, to, calendarType?)	(from: Date, to: Date, calendarType?: CalendarType) => number	"shamsi"	Calendar-month distance between two dates; month length depends on calendarType.
isSameDay(a, b) / isBefore(a, b) / isAfter(a, b)	(a: Date, b: Date) => boolean	—	Basic day-level comparisons.
isToday(date) / isPast(date) / isFuture(date)	(date: Date) => boolean	—	Relative-to-now comparisons.
minDate(...dates) / maxDate(...dates)	(...dates: Date[]) => Date	—	The earliest/latest date in a list.
clampDate(date, { min?, max? })	(date: Date, bounds: { min?: Date; max?: Date }) => Date	—	Clamps date between optional min/max bounds (inclusive).
eachDayOfRange(from, to)	(from: Date, to: Date) => Date[]	—	Inclusive day list between from and to.
isWithinRange(date, range)	(date: Date, range: DateRange) => boolean	—	True when date falls within range (inclusive, missing bounds are open-ended).
rangeLengthInDays(range)	(range: DateRange) => number	—	Inclusive day count spanned by a range, or 0 if incomplete.
validateRange(range, options?)	(range: DateRange, options?: RangeValidationOptions) => "incomplete" \| "inverted" \| "too-short" \| "too-long" \| "in-past" \| "disabled-date" \| null	—	Validates a from/to range against reservation-style constraints: ordering, minimum/maximum stay length, past dates, and specific blocked dates. Returns null when valid, or a machine-readable reason otherwise.

Digits

Prop	Type	Default	Description
toPersianDigits(value)	(value: string) => string	—	Converts every plain 0-9 digit in a string to its Persian (۰-۹) equivalent.
toLatinDigits(value)	(value: string) => string	—	Converts Persian/Arabic-Indic digits back to plain 0-9. Alias of normalizePersianDigits.

DateOptions

Prop	Type	Default	Description
calendarType	"shamsi" \| "miladi"	"shamsi"	"shamsi" is the Jalali/Solar Hijri calendar (default, Iran-first). "miladi" is the Gregorian calendar.
locale	"fa" \| "en"	calendarType === "shamsi" ? "fa" : "en"	Month/weekday names.
digits	"fa" \| "en"	calendarType === "shamsi" ? "fa" : "en"	Output digit style.

Edit this page on GitHub

PreviousNormalize Persian Digits NextPersian Date (Zod)