Jalaali Date-Time Picker 🗓️

Production-ready Jalali (Persian) date + time picker for React / Next.js.

• Fully typed
• Tree-shakable ESM build
• Built on Tailwind + ShadCN
• Headless – bring your own theme if you like
• Keyboard navigation (← ↑ → ↓ + Enter)

Installation

npm install jalaali-date-time-picker

Peer Dependencies

Ensure the following packages are installed in your project:

• react (version 18 or higher)
• react-dom (version 18 or higher)
• tailwindcss (version 3 or higher)

Tailwind Configuration

You must include this path in your tailwind.config.js (or tailwind.config.ts):

module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./node_modules/jalaali-date-time-picker/dist/**/*.{js,mjs}", // required
  ],
}

This ensures Tailwind can process the component styles properly.

RTL Support

To render correctly, the parent document must be in RTL mode:

<div lang="fa" dir="rtl">

Usage

import { JalaaliDateTimePicker } from "jalaali-date-time-picker";

export default function Page() {
  return (
    <div dir="rtl">
      <JalaaliDateTimePicker onChange={(d) => console.log(d)} />
    </div>
  );
}

Interactive Example

See the full interactive demo here.

Props

| Prop | Type | Default | Description | |------------------|---------------------------------------------------|--------------------|-------------| | className | string | "" | Optional Tailwind class | | defaultValue | Date | new Date() | Default initial date | | value | Date | undefined | Controlled value | | minDate | Date | 1970-01-01 | Minimum date allowed | | maxDate | Date | 2100-12-31 | Maximum date allowed | | disablePast | boolean | false | Disallow past dates | | disableFuture | boolean | false | Disallow future dates | | minuteStep | number | 1 | Step for minute selection | | disabled | boolean | false | Disable the picker | | showTime | boolean | true | Show time picker | | format | "jalali" \| "gregorian" | "jalali" | Date format to display | | clearable | boolean | false | Show "clear" button | | inline | boolean | false | Render in-place instead of a modal | | trigger | ReactNode | undefined | Custom trigger component | | formatLabel | (date: Date) => string | undefined | Custom display label formatter | | onChange | (date: Date) => void | undefined | Callback when value changes | | onOpenChange | (open: boolean) => void | undefined | Callback when modal opens/closes | | onClear | (prev: Date \| null) => void | undefined | Callback when cleared | | inputRef | React.RefObject<HTMLInputElement> | undefined | Ref to hidden input | | placeholderLabel | string | "انتخاب تاریخ و زمان" | Placeholder | | inputFieldProps | InputFieldProps | undefined | Pass props from RHF, Formik, etc. |

Dependencies

This package uses the following runtime dependencies:

• jalaali-js - Jalali calendar conversion utilities
• @radix-ui components - Headless UI primitives (dialog, select, separator, slot)

All icons are custom SVG implementations (no external icon library required).

Goal

The long-term goal of this package is to make it as lightweight and dependency-free as possible, reducing external reliance without compromising functionality or design.

Recent optimizations:

• ✅ Icon rendering - Replaced lucide-react with custom SVG icons, eliminating the dependency entirely

Contributing

Contributions are welcome and encouraged! 🙌

If you find a bug or have a feature request, please open an issue.

To contribute:

1. Fork the repository
2. Create a new branch: git checkout -b feature-name
3. Make your changes and commit them
4. Push to your fork and submit a pull request

Author Information

👤 Ali Julaee Rad

• GitHub: alijeyrad
• LinkedIn: in/ali-julaee-rad
• Email: [email protected]

Made with ❤️ in Iran.