HiDtp - Jalali (Persian) Date & Time Picker

A modern, customizable Jalali (Persian) date and time picker component for React applications. Built with TypeScript and designed for RTL (Right-to-Left) layouts.

Features

• 🗓️ Jalali Calendar Support: Full Persian calendar implementation
• ⏰ Time Picker: 12/24 hour format with seconds support
• 🎯 Multiple Selection Modes: Single, multiple, and range selection
• ⌨️ Keyboard Navigation: Full keyboard accessibility
• 🎨 Customizable Icons: Pass your own icon set
• 📱 Responsive Design: Works on all screen sizes
• 🎭 RTL Support: Built for Persian/Arabic layouts
• 🔧 TypeScript: Full type safety
• 🎨 Tailwind CSS: Styled with utility classes

Installation

npm install hi-dtp
# or
yarn add hi-dtp
# or
pnpm add hi-dtp

Basic Usage

import { JalaliDatePicker } from 'hi-dtp';

function App() {
  const [selectedDate, setSelectedDate] = useState(null);

  return (
    <JalaliDatePicker
      value={selectedDate}
      onChange={setSelectedDate}
      mode="single"
      placeholder="تاریخ را انتخاب کنید"
    />
  );
}

Advanced Usage

import { JalaliDatePicker } from 'hi-dtp';

function AdvancedExample() {
  const [selectedDates, setSelectedDates] = useState([]);

  return (
    <JalaliDatePicker
      value={selectedDates}
      onChange={setSelectedDates}
      mode="multiple"
      pickerType="dateAndClock"
      showTime={true}
      timeFormat24h={false}
      showSeconds={true}
      size="lg"
      enableKeyboardNavigation={true}
      disablePastDates={true}
      icons={{
        calendar: {
          src: '/path/to/calendar.svg',
          alt: 'Calendar Icon',
          width: 20,
          height: 20,
        },
      }}
    />
  );
}

Props

JalaliDatePickerProps

| Prop | Type | Default | Description | | -------------------------- | --------------------------------------------------- | ------------------------ | -------------------------- | | value | DatePickerValue | undefined | Selected date(s) | | onChange | (date: DatePickerValue, time?: TimeValue) => void | undefined | Change handler | | mode | 'single' \| 'multiple' \| 'range' | 'multiple' | Selection mode | | pickerType | 'date' \| 'clock' \| 'dateAndClock' | 'dateAndClock' | Picker type | | showTime | boolean | true | Show time picker | | timeFormat24h | boolean | false | Use 24-hour format | | showSeconds | boolean | false | Show seconds picker | | placeholder | string | 'تاریخ را انتخاب کنید' | Input placeholder | | disabled | boolean | false | Disable the picker | | disabledDates | JalaliDate[] | [] | Dates to disable | | disablePastDates | boolean | false | Disable past dates | | className | string | '' | Additional CSS classes | | size | 'sm' \| 'md' \| 'lg' | 'sm' | Component size | | enableKeyboardNavigation | boolean | false | Enable keyboard navigation | | onKeyDown | (event: KeyboardEvent) => void | undefined | Keyboard event handler | | icons | Partial<IconsObject> | defaultIcons | Custom icons |

Types

type DatePickerValue = JalaliDate | JalaliDate[] | { start: JalaliDate; end: JalaliDate } | null;

interface JalaliDate {
  year: number;
  month: number;
  day: number;
}

interface TimeValue {
  hour: number;
  minute: number;
  second: number;
}

interface IconsObject {
  calendar: IconProps;
  clear: IconProps;
  next: IconProps;
  previous: IconProps;
}

interface IconProps {
  src: string;
  alt: string;
  width: number;
  height: number;
}

Utility Functions

The package also exports useful utility functions:

import {
  getTodayJalali,
  formatJalaliDate,
  formatTime,
  toPersianDigits,
  toEnglishDigits,
  compareJalaliDates,
  isJalaliDateEqual,
  isDateBetween,
  getNextDate,
  getPrevDate,
  jalaliToGregorian,
  gregorianToJalali,
} from 'hi-dtp';

// Get today's Jalali date
const today = getTodayJalali();

// Format a Jalali date
const formatted = formatJalaliDate(today); // "۱۴۰۲/۱۲/۲۵"

// Convert to Persian digits
const persian = toPersianDigits('1402'); // "۱۴۰۲"

// Compare dates
const isAfter = compareJalaliDates(date1, date2) > 0;

Keyboard Navigation

When enableKeyboardNavigation is true:

• Arrow Keys: Navigate between dates
• Enter/Space: Select current date
• Escape: Close picker

Styling

The component uses Tailwind CSS classes. You can customize the appearance by:

1. Passing custom className props
2. Overriding Tailwind classes in your CSS
3. Using the size prop for different sizes

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.