Persian Calendar Library

A modern, customizable Persian/Shamsi calendar component for React with RTL support, range selection, and comprehensive theming options.

Features

• 🌍 Persian/Shamsi Calendar Support - Full support for Persian calendar system
• 🔄 Gregorian Calendar Support - Also supports standard Gregorian calendar
• 🎨 Comprehensive Theming - Light, dark, and auto themes with custom CSS classes
• 📅 Range Selection - Select date ranges with visual feedback
• 🚫 Flexible Date Disabling - Disable past, future, or both with disableMode prop
• 🎯 RTL Support - Full right-to-left layout support for Persian
• 📱 Responsive Design - Works on desktop, tablet, and mobile
• 🎨 Tailwind CSS - Built with Tailwind CSS for easy customization
• 🔧 TypeScript - Full TypeScript support with comprehensive type definitions
• 🧪 Comprehensive Testing - Unit tests and E2E tests with Playwright

Installation

npm install ziprin-persian-calendar

Prerequisites

This library requires the following dependencies to be installed in your project:

Required Dependencies

• React >= 18.0.0
• React DOM >= 18.0.0

Optional Dependencies

• Tailwind CSS (for styling - the library is built with Tailwind CSS classes)

Installation with Dependencies

# Install the calendar library
npm install ziprin-persian-calendar

# Install React (if not already installed)
npm install react react-dom

# Install Tailwind CSS (optional, for styling)
npm install tailwindcss

TypeScript Support

The library includes full TypeScript support. Make sure you have TypeScript installed:

npm install -D typescript @types/react @types/react-dom

Quick Start

Basic Usage

import React from 'react';
import { Calendar } from 'ziprin-persian-calendar';

function App() {
  const handleDateSelect = (date: Date) => {
    console.log('Selected date:', date);
  };

  return (
    <Calendar
      system="persian"
      onDateSelect={handleDateSelect}
      className="shadow-lg"
    />
  );
}

With Range Selection

import React from 'react';
import { Calendar } from 'ziprin-persian-calendar';

function App() {
  const handleRangeSelect = (range: { start: Date; end: Date | null }) => {
    console.log('Selected range:', range);
  };

  return (
    <Calendar
      system="persian"
      range={true}
      onRangeSelect={handleRangeSelect}
      disableMode="past"
    />
  );
}

With Tailwind CSS

Make sure you have Tailwind CSS configured in your project for the best styling experience:

# Install Tailwind CSS
npm install -D tailwindcss postcss autoprefixer

# Initialize Tailwind CSS
npx tailwindcss init -p

Then configure your tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/ziprin-persian-calendar/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Props

Calendar System & Configuration

| Prop | Type | Default | Description | |------|------|---------|-------------| | system | "persian" \| "gregorian" | "persian" | Calendar system to use | | range | boolean | false | Enable range selection mode | | disableMode | "past" \| "future" \| "both" \| "none" | "past" | Which dates to disable | | weekStart | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 0 | First day of week (0=Sunday) | | minDate | Date \| string | - | Minimum selectable date | | maxDate | Date \| string | - | Maximum selectable date | | initialDate | Date \| string | new Date() | Initial date to display | | isDateDisabled | (date: Date) => boolean | - | Custom date disabling function |

Event Handlers

| Prop | Type | Description | |------|------|-------------| | onDateSelect | (date: Date) => void | Called when a single date is selected | | onRangeSelect | (range: DateRange) => void | Called when a date range is selected | | onMonthChange | (year: number, month: number) => void | Called when month changes | | onYearChange | (year: number) => void | Called when year changes |

Customization

| Prop | Type | Default | Description | |------|------|---------|-------------| | className | string | "" | Additional CSS classes for container | | classes | CalendarClasses | {} | Custom CSS classes for specific elements | | theme | "light" \| "dark" \| "auto" | "light" | Theme to use | | size | "sm" \| "md" \| "lg" | "md" | Size variant | | variant | "default" \| "minimal" \| "bordered" | "default" | Visual variant |

Accessibility

| Prop | Type | Default | Description | |------|------|---------|-------------| | ariaLabel | string | "Calendar" | ARIA label for the calendar | | ariaDescribedBy | string | - | ARIA describedby reference |

Examples

Basic Persian Calendar

import { Calendar } from 'ziprin-persian-calendar'

<Calendar
  system="persian"
  onDateSelect={(date) => console.log('Selected:', date)}
/>

Range Selection with Custom Styling

import { Calendar } from 'ziprin-persian-calendar'

<Calendar
  system="persian"
  range={true}
  disableMode="past"
  theme="dark"
  size="lg"
  classes={{
    container: "custom-container",
    header: "custom-header",
    daysGrid: "custom-days-grid"
  }}
  onRangeSelect={(range) => {
    console.log('Start:', range.start)
    console.log('End:', range.end)
  }}
/>

Gregorian Calendar with Future Dates Disabled

import { Calendar } from '@ziprin/persian-calendar'

<Calendar
  system="gregorian"
  disableMode="future"
  minDate="2024-01-01"
  maxDate="2025-12-31"
  onDateSelect={(date) => console.log('Selected:', date)}
/>

Custom Date Disabling

import { Calendar } from '@ziprin/persian-calendar'

<Calendar
  system="persian"
  isDateDisabled={(date) => {
    // Disable weekends
    const day = date.getDay()
    return day === 0 || day === 6
  }}
  onDateSelect={(date) => console.log('Selected:', date)}
/>

DisableMode Options

• "past" - Disable all dates before today
• "future" - Disable all dates after today
• "both" - Disable all dates except today
• "none" - Allow all dates (no restrictions)

Custom CSS Classes

You can customize the appearance using the classes prop:

const customClasses = {
  container: "my-custom-container",
  header: "my-custom-header",
  headerContent: "my-custom-header-content",
  monthPicker: "my-custom-month-picker",
  yearPicker: "my-custom-year-picker",
  weekDaysHeader: "my-custom-week-days-header",
  daysGrid: "my-custom-days-grid"
}

<Calendar classes={customClasses} />

Hooks

useCalendar

For advanced usage, you can use the useCalendar hook directly:

import { useCalendar } from '@ziprin/persian-calendar'

function MyCalendar() {
  const calendar = useCalendar({
    system: "persian",
    rangeMode: true,
    disableMode: "past"
  })

  return (
    <div>
      <button onClick={calendar.prevMonth}>Previous</button>
      <span>{calendar.monthName} {calendar.yearNumber}</span>
      <button onClick={calendar.nextMonth}>Next</button>
      
      {calendar.days.map((day) => (
        <button
          key={day.date.toISOString()}
          onClick={() => calendar.selectDate(day.date)}
          disabled={day.isDisabled}
        >
          {day.day}
        </button>
      ))}
    </div>
  )
}

Utilities

toPersianNumber

Convert English numbers to Persian script:

import { toPersianNumber } from '@ziprin/persian-calendar'

const persianNumber = toPersianNumber(123) // "۱۲۳"

Browser Support

• Chrome >= 88
• Firefox >= 85
• Safari >= 14
• Edge >= 88

Browser Support

This library supports all modern browsers:

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

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build library
npm run build:lib

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Support

If you have any questions or need help, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue

Changelog

See CHANGELOG.md for a list of changes and version history.