Accessible, themeable Jalali (Persian) calendar utilities and React components — built once, so you never have to rebuild a Jalali calendar from scratch again.
Every React/Next.js project that needs a Jalali calendar ends up rebuilding the same thing: date conversion, leap-year handling, RTL layout, holiday data, keyboard navigation, mobile behavior. Usually from scratch, usually a little differently each time, and usually without full accessibility support.
This project extracts that work into two independently versioned, fully tested packages — so you install, theme, and ship, instead of reimplementing.
- Correct by construction — conversion built on the well-tested
jalaali-jsalgorithm, validated against independent fixtures, with full Jalali year range support. - Holidays out of the box — official Iranian holidays load automatically, with visible tooltips, a monthly holiday list, and screen-reader announcements. Fully optional and swappable.
- Genuinely accessible — roving-focus keyboard navigation, ARIA grid semantics, focus trap and restoration,
prefers-reduced-motionsupport, and forced-colors compatibility. Not bolted on afterward. - Responsive by default — a centered dialog on desktop, a native-feeling bottom drawer with drag-to-dismiss on mobile, with a configurable breakpoint.
- Deeply themeable — 180+ CSS custom properties and stable
data-*hooks cover every visual part, from the calendar grid down to the input trigger field. No forking required to match your design system. - Framework-agnostic core —
persian-calendar-corehas zero React dependency, so date math, validation, and grid generation are usable anywhere JavaScript runs. - Tiny and dependency-conscious — React and React DOM are peer dependencies only; the core package ships with a single focused date-conversion dependency.
| Package | Purpose |
|---|---|
@seydanloo/persian-calendar-core |
Framework-agnostic conversion, validation, weekdays, digit normalization, locale data, month-grid generation, and optional holiday providers. |
@seydanloo/persian-calendar |
Accessible, controlled/uncontrolled React <PersianCalendar /> and <PersianDatePicker />, with a responsive dialog/drawer and full theming support. |
Both are published independently — if you only need date math (e.g. for a backend or a non-React app), install -core alone.
- Node.js 20+
- React / React DOM 18.2–19.x (React package only)
npm install @seydanloo/persian-calendar-coreOr, for the React components:
npm install @seydanloo/persian-calendar react react-domimport "@seydanloo/persian-calendar/styles.css";import { PersianDatePicker } from "@seydanloo/persian-calendar";
import "@seydanloo/persian-calendar/styles.css";
export function BookingDate() {
return (
<PersianDatePicker
label="تاریخ رزرو"
onChange={(date) => console.log(date)}
/>
);
}That's it — holidays, RTL layout, keyboard navigation, and responsive mobile behavior all work with zero additional configuration.
:root {
--pc-color-selected: #2563eb;
--pc-radius-day: 8px;
--pc-input-border-radius: 6px;
}Every meaningful part of the calendar and the date-picker's trigger field is themeable this way — see the React package README for the full variable reference.
import { toGregorian, isLeapJalaliYear, generateMonthGrid } from "@seydanloo/persian-calendar-core";
toGregorian({ year: 1403, month: 12, day: 30 }); // { year: 2025, month: 3, day: 20 }
isLeapJalaliYear(1403); // true- Iranian holidays load automatically and remain selectable — blocking selection is entirely your decision via
isDateDisabled. - Holiday descriptions are available through accessible cell tooltips and a keyboard-navigable monthly list, triggered from the calendar footer next to Today.
- On mobile, the date picker becomes a bottom drawer with a visible drag handle and handle-only swipe-to-dismiss; on desktop it's a centered dialog. The breakpoint is configurable.
- Weeks start on Saturday. Digit input accepts Latin, Persian, and Arabic-Indic numerals. Native
Dateinterop is explicitly UTC-based, documented, and consistent everywhere in the package.
See the core package README and React package README for full API references, theming tables, keyboard controls, accessibility notes, and holiday-data attribution.
This isn't an accessibility afterthought — it's part of the spec:
- Full roving-focus keyboard navigation across day, month, and year selection grids (arrows, Home/End, PageUp/PageDown, Enter/Space, Escape).
- Proper ARIA grid/dialog semantics,
aria-selected,aria-current="date",aria-disabled, and live-region announcements. - Labeled dialog/drawer with a focus trap, Escape-to-close, click-outside-to-close, and focus restoration on close.
- Visible focus states, logical-property RTL layout,
prefers-reduced-motionsupport, andforced-colors(Windows High Contrast) compatibility.
This is a pnpm workspace using Changesets for independent package versioning.
pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm lint:packagepnpm check runs the full pre-release verification sequence used before every publish.
pnpm changeset— describe the user-facing change.- Commit the generated
.changeset/*.mdfile alongside the implementation. pnpm version-packageswhen preparing a release.- Review the resulting package versions, changelogs, and lockfile.
pnpm check.pnpm release(requires npm authentication).
Both packages emit ESM and CommonJS builds, ship type declarations and source maps, and are validated with publint before every release.
Package code is MIT licensed.
The default holiday experience uses the core Iran holiday provider automatically. Its date-holidays dependency is ISC licensed, while the underlying Iran holiday data is CC BY-SA 3.0, primarily sourced from Wikipedia per upstream's own attribution practice. Consumers who use the default provider inherit that attribution requirement for the holiday data specifically — the rest of this project remains MIT. No upstream holiday YAML/JSON was copied into this repository; holiday data is computed at runtime through the date-holidays dependency.
Issues and pull requests are welcome. Please open an issue before starting significant work so the direction can be agreed on first.
Built by Reza Seydanloo — reza.seydanloo.83@gmail.com · linkedin.com/in/seydanloo