Persian Calendar Suite

A comprehensive Persian (Jalali/Shamsi) calendar suite for React with datepicker, range picker, event calendar, and multiple output formats.


Live Demo | Documentation

Table of Contents

- Installation
- Compatibility
- Quick Start
- Components
- PersianDateTimePicker
- PersianDateRangePicker
- PersianTimePicker
- PersianCalendar
- PersianTimeline
- PersianMoment
- Theme Customization
- Output Formats
- Programmatic Control
- Examples
- Browser Support
- License

Installation

``bash
npm install persian-calendar-suite
`

or with yarn:

`bash
yarn add persian-calendar-suite
`

Compatibility

- React: +16.8 (Hooks required)
- React DOM: +16.8
- Next.js: +12 (Client-side components)
- Node: 12+

$3

`bash
npm install react react-dom
`

Quick Start

$3

`jsx
import React, { useState } from 'react';
import { PersianDateTimePicker } from 'persian-calendar-suite';

function App() {
const [date, setDate] = useState(null);

return (
value={date}
onChange={setDate}
/>
);
}
`

$3

`jsx
'use client'; // Required for Next.js 13+ App Router

import { useState } from 'react';
import { PersianDateTimePicker } from 'persian-calendar-suite';

export default function Page() {
const [date, setDate] = useState(null);

return (
value={date}
onChange={setDate}
/>
);
}
`

Components

$3

Single date and time picker with Shamsi calendar.

#### Import

`jsx
import { PersianDateTimePicker } from 'persian-calendar-suite';
`

#### Basic Usage

`jsx
const [value, setValue] = useState(null);

value={value}
onChange={setValue}
/>
`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| value | string \| number \| null | null | Selected date value |
| onChange | (value: string \| number) => void | - | Callback when date changes |
| showTime | boolean | true | Show time picker |
| minuteStep | number | 1 | Minute step interval |
| outputFormat | 'iso' \| 'shamsi' \| 'gregorian' \| 'hijri' \| 'timestamp' | 'iso' | Output format |
| showFooter | boolean | true | Show OK/Cancel buttons |
| theme | ThemeObject | {} | Theme customization |
| disabledHours | number[] | [] | Array of disabled hours |
| minDate | string \| Date | null | Minimum selectable date |
| maxDate | string \| Date | null | Maximum selectable date |
| persianNumbers | boolean | false | Display numbers in Persian digits |
| rtlCalendar | boolean | false | Start calendar from right (Sunday first) |

#### Example with Options

`jsx
value={value}
onChange={setValue}
showTime={true}
outputFormat="shamsi"
showFooter={false}
theme={{
primaryColor: '#6366f1',
circularDates: true
}}
/>
`

---

$3

Date range picker with dual calendars.

#### Import

`jsx
import { PersianDateRangePicker } from 'persian-calendar-suite';
`

#### Basic Usage

`jsx
const [range, setRange] = useState(null);

value={range}
onChange={setRange}
/>
`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| value | [string, string] \| null | null | Selected range [start, end] |
| onChange | (value: [string, string]) => void | - | Callback when range changes |
| placeholder | [string, string] | ['تاریخ شروع', 'تاریخ پایان'] | Placeholder text |
| disabled | boolean | false | Disable the picker |
| outputFormat | 'iso' \| 'shamsi' \| 'gregorian' \| 'hijri' \| 'timestamp' | 'iso' | Output format |
| showFooter | boolean | true | Show OK/Cancel buttons |
| theme | ThemeObject | {} | Theme customization |
| minDate | string \| Date | null | Minimum selectable date |
| maxDate | string \| Date | null | Maximum selectable date |
| persianNumbers | boolean | false | Display numbers in Persian digits |
| rtlCalendar | boolean | false | Start calendar from right (Sunday first) |

#### Example with Options

`jsx
value={range}
onChange={setRange}
placeholder={['Start', 'End']}
outputFormat="timestamp"
theme={{
primaryColor: '#10b981'
}}
/>
`

---

$3

Standalone time picker component with range support.

#### Import

`jsx
import { PersianTimePicker } from 'persian-calendar-suite';
`

#### Basic Usage

`jsx
const [time, setTime] = useState('');

value={time}
onChange={setTime}
/>
`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| value | string \| string[] | '' | Selected time value (HH:MM or [HH:MM, HH:MM] for range) |
| onChange | (value: string \| string[]) => void | - | Callback when time changes |
| defaultValue | string \| 'now' | null | Default time ('now' or 'HH:MM') |
| minuteStep | number | 1 | Minute step interval |
| disabledHours | number[] | [] | Array of disabled hours |
| placeholder | string | 'انتخاب زمان' | Placeholder text |
| persianNumbers | boolean | false | Display numbers in Persian digits |
| isRange | boolean | false | Enable time range selection |
| theme | ThemeObject | {} | Theme customization |

#### Example with Options

`jsx
value={time}
onChange={setTime}
defaultValue="now"
minuteStep={15}
disabledHours={[0, 1, 2, 22, 23]}
theme={{
primaryColor: '#10b981'
}}
/>
`

#### Time Range Picker

`jsx
const [timeRange, setTimeRange] = useState([]);

value={timeRange}
onChange={setTimeRange}
isRange={true}
minuteStep={15}
/>
// Output: ["09:00", "17:00"]
`

---

$3

Timeline component for displaying chronological events with Persian dates.

#### Import

`jsx
import { PersianTimeline } from 'persian-calendar-suite';
`

#### Basic Usage

`jsx
const [events] = useState([
{
id: 1,
date: '2025-12-10',
time: '14:30',
title: 'Project Started',
description: 'Initial project setup and planning',
color: '#10b981',
icon: '🚀'
},
{
id: 2,
date: '2025-12-15',
title: 'Milestone Reached',
color: '#6366f1',
image: '/milestone.jpg'
}
]);

events={events}
onEventClick={(event) => console.log(event)}
/>
`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| events | Event[] | [] | Array of timeline events |
| onEventClick | (event: Event) => void | - | Callback when event is clicked |
| direction | 'vertical' \| 'horizontal' | 'vertical' | Timeline orientation |
| markerShape | 'circular' \| 'rect' | 'circular' | Shape of event markers |
| showIcons | boolean | true | Show event icons/images |
| alternating | boolean | true | Alternate event sides (vertical only) |
| persianNumbers | boolean | false | Display numbers in Persian digits |
| theme | ThemeObject | {} | Theme customization |

#### Event Object

`typescript
{
id: number; // Unique identifier
date: string; // ISO date string (YYYY-MM-DD)
time?: string; // Optional time (HH:mm)
title: string; // Event title
description?: string; // Event description
color?: string; // Event color (hex)
icon?: string | ReactNode; // Event icon (emoji or component)
image?: string; // Event image URL
}
`

#### Timeline Types

Vertical Timeline (default)
`jsx
events={events}
direction="vertical"
alternating={true}
/>
`

Horizontal Timeline
`jsx
events={events}
direction="horizontal"
/>
`

Custom Markers
`jsx
events={events}
markerShape="rect"
showIcons={true}
/>
`

#### Advanced Example

`jsx
const timelineEvents = [
{
id: 1,
date: '2025-01-15',
time: '09:00',
title: 'Project Kickoff',
description: 'Initial team meeting and project planning session',
color: '#10b981',
icon: '🎯'
},
{
id: 2,
date: '2025-02-20',
title: 'Design Phase Complete',
description: 'UI/UX designs approved and ready for development',
color: '#6366f1',
image: '/design-preview.jpg'
},
{
id: 3,
date: '2025-03-30',
time: '16:00',
title: 'Beta Release',
description: 'First beta version released to testing team',
color: '#f59e0b',
icon:
}
];

events={timelineEvents}
direction="vertical"
markerShape="circular"
alternating={true}
persianNumbers={true}
onEventClick={(event) => {
console.log('Timeline event clicked:', event);
}}
theme={{
primaryColor: '#6366f1',
lineColor: '#e5e7eb',
markerSize: '16px',
eventRadius: '12px'
}}
/>
`

---

$3

Jalali date arithmetic utility for date calculations and conversions.

#### Import

`jsx
import persianMoment from 'persian-calendar-suite/PersianMoment';
`

#### Basic Usage

`jsx
// Create Persian dates
const m1 = persianMoment('1404/12/30', 'jYYYY/jMM/jDD');
const m2 = persianMoment('1404/01/02', 'jYYYY/jMM/jDD');

// Calculate differences
console.log(m2.diff(m1, 'day')); // 3
console.log(m2.diff(m1, 'jMonth')); // 1

// Format conversion
console.log(m1.format('YYYY/MM/DD')); // 2025/03/19
console.log(m1.format('jYYYY/jMM/jDD')); // 1404/12/30
`

#### Supported Input Formats

- Jalali: '1404/12/30' with format 'jYYYY/jMM/jDD'
- Gregorian: '2025/03/19' with format 'YYYY/MM/DD'
- ISO: '2025-03-19' (no format needed)

#### Methods

diff(other, unit, outputFormat)
- unit: 'day', 'jDay', 'jMonth', 'jYear'
- outputFormat: 'number', 'persian', 'persian-text'

format(format)
- format: 'jYYYY/jMM/jDD', 'YYYY/MM/DD', 'iso'

#### Output Formats

`jsx
const diff = m2.diff(m1, 'day', 'persian-text');
// Output: "۳ روز"

const diff2 = m2.diff(m1, 'jMonth', 'persian');
// Output: "۱"
`

---

$3

Full-featured calendar with event management (like FullCalendar).

#### Import

`jsx
import { PersianCalendar } from 'persian-calendar-suite';
`

#### Basic Usage

`jsx
const [events, setEvents] = useState([]);

events={events}
onEventCreate={(event) => setEvents([...events, event])}
onEventUpdate={(updated) => setEvents(events.map(e => e.id === updated.id ? updated : e))}
onEventDelete={(deleted) => setEvents(events.filter(e => e.id !== deleted.id))}
/>
`

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| events | Event[] | [] | Array of event objects |
| onEventCreate | (event: Event) => void | - | Callback when event is created |
| onEventUpdate | (event: Event) => void | - | Callback when event is updated |
| onEventDelete | (event: Event) => void | - | Callback when event is deleted |
| onEventClick | (event: Event) => void | - | Callback when event is clicked |
| initialView | 'day' \| 'week' \| 'month' | 'month' | Initial view mode |
| editable | boolean | true | Enable event creation/editing |
| showWeekends | boolean | true | Show weekend days |
| headerFormat | 'full' \| 'short' | 'full' | Header format |
| disabledHours | number[] | [] | Array of disabled hours (0-23) |
| theme | ThemeObject | {} | Theme customization |

#### Event Object

`typescript
{
id: number; // Unique identifier
date: string; // ISO date string (YYYY-MM-DD)
startTime: string; // Start time (HH:mm)
endTime: string; // End time (HH:mm)
title: string; // Event title
color: string; // Event color (hex)
description?: string; // Event description (optional)
isAllDay?: boolean; // All-day event flag
isRecurring?: boolean; // Recurring event flag
recurringType?: 'daily' | 'weekly' | 'monthly' | 'yearly'; // Recurrence pattern
recurringEnd?: string; // End date for recurring events
isMultiDay?: boolean; // Multi-day event flag
endDate?: string; // End date for multi-day events
readOnly?: boolean; // Read-only event flag (cannot be edited)
}
`

#### Creating Events

Day View: Click on hour slots (00:00 - 23:00)
`jsx
// User clicks on 09:00 slot
// Modal opens with startTime: "09:00", endTime: "10:00"
`

Week View: Click on time cells for any day
`jsx
// User clicks on Tuesday 14:00
// Modal opens for that specific day and time
`

Month View: Click on day cells
`jsx
// User clicks on day 15
// Modal opens with default time 09:00
`

#### Editing Events

Click on any existing event to open the edit modal:
- Modify title, start/end time, color, description
- Delete button available in modal
- Changes trigger onEventUpdate callback

#### Advanced Features

Event Types:
- All-day events: Check "رویداد تمام روز" to create events spanning entire days
- Multi-day events: Check "رویداد چند روزه" to create events spanning multiple days
- Recurring events: Check "رویداد تکراری" for daily/weekly/monthly/yearly repetition
- Today button: Quick navigation to current date
- Event tooltips: Hover over events to see full details

Overlap Detection:
- Shows orange badge with count (e.g., "2 تداخل")
- Highlights slots with light orange background
- Displays events side-by-side in day view

Visual Indicators:
- All-day events: Gradient background with dashed border and sun icon
- Recurring events: Refresh icon after title
- Multi-day and recurring events are mutually exclusive

#### Full Example

`jsx
const [events, setEvents] = useState([
{
id: 1,
date: '2025-12-10',
startTime: '09:00',
endTime: '10:00',
title: 'Team Meeting',
color: '#10b981',
description: 'Weekly team sync',
isRecurring: true,
recurringType: 'weekly'
},
{
id: 2,
date: '2025-12-11',
title: 'Company Event',
color: '#ef4444',
isAllDay: true
}
]);

events={events}
onEventCreate={(event) => {
console.log('Created:', event);
setEvents([...events, event]);
}}
onEventUpdate={(updated) => {
console.log('Updated:', updated);
setEvents(events.map(e => e.id === updated.id ? updated : e));
}}
onEventDelete={(deleted) => {
console.log('Deleted:', deleted);
setEvents(events.filter(e => e.id !== deleted.id));
}}
onEventClick={(event) => {
console.log('Clicked:', event);
}}
initialView="day"
editable={true}
theme={{
primaryColor: '#6366f1'
}}
disabledHours={[0, 1, 2, 22, 23]} // Disable late night/early morning hours
/>
`

Theme Customization

All components support theme customization via the theme prop.

$3

`typescript
{
primaryColor?: string; // Primary color (default: '#1890ff')
backgroundColor?: string; // Background color (default: '#ffffff')
textColor?: string; // Text color (default: '#000000')
borderColor?: string; // Border color (default: '#d9d9d9')
hoverColor?: string; // Hover color (default: '#f0f0f0')
selectedTextColor?: string; // Selected text color (default: '#ffffff')
circularDates?: boolean; // Circular date cells (default: false)
// Calendar specific
headerBg?: string; // Header background (default: '#fafafa')
eventRadius?: string; // Event border radius (default: '6px')
shadow?: string; // Shadow (default: '0 2px 8px rgba(0,0,0,0.08)')
}
`

$3

`jsx
const customTheme = {
primaryColor: '#6366f1',
backgroundColor: '#ffffff',
textColor: '#1f2937',
borderColor: '#e5e7eb',
hoverColor: '#f3f4f6',
circularDates: true
};

value={value}
onChange={setValue}
theme={customTheme}
/>
`

Output Formats

$3

`
2025-12-10T14:30:00
`

$3

`
1404/09/20 14:30
`

$3

`
2025/12/10 14:30
`

$3

`
1446/06/08 14:30
`

$3

`
1702217400000
`

$3

`jsx
value={value}
onChange={setValue}
outputFormat="shamsi" // or 'iso', 'gregorian', 'hijri', 'timestamp'
/>
`

Programmatic Control

$3

All components are controlled - you manage the state:

`jsx
const [date, setDate] = useState(null);
const [range, setRange] = useState(null);
const [events, setEvents] = useState([]);

// Read current values anytime
console.log('Current date:', date);
console.log('Current range:', range);
console.log('All events:', events);
`

$3

#### Set Date/Time

`jsx
const [date, setDate] = useState(null);

// Set to current date
setDate(new Date().toISOString());

// Set specific date (ISO format)
setDate('2025-12-10T14:30:00');

// Set via timestamp
setDate(1702217400000);

// Clear date
setDate(null);
`

#### Set Date Range

`jsx
const [range, setRange] = useState(null);

// Set range
setRange(['2025-12-01T00:00:00', '2025-12-31T23:59:59']);

// Set last 7 days
const end = new Date();
const start = new Date(end.getTime() - 7 24 60 60 1000);
setRange([start.toISOString(), end.toISOString()]);

// Clear range
setRange(null);
`

#### Manage Events

`jsx
const [events, setEvents] = useState([]);

// Add event programmatically
const addEvent = () => {
const newEvent = {
id: Date.now(),
date: '2025-12-15',
startTime: '10:00',
endTime: '11:00',
title: 'New Meeting',
color: '#3b82f6',
description: 'Auto-created event'
};
setEvents([...events, newEvent]);
};

// Update specific event
const updateEvent = (id, updates) => {
setEvents(events.map(e =>
e.id === id ? { ...e, ...updates } : e
));
};

// Delete event
const deleteEvent = (id) => {
setEvents(events.filter(e => e.id !== id));
};

// Clear all events
setEvents([]);

// Load events from API
fetch('/api/events')
.then(res => res.json())
.then(data => setEvents(data));
`

$3

#### Auto-select Today

`jsx
const [date, setDate] = useState(new Date().toISOString());

// Update to today on mount
useEffect(() => {
setDate(new Date().toISOString());
}, []);
`

#### Filter Events by Date

`jsx
const [events, setEvents] = useState([...]);
const [selectedDate, setSelectedDate] = useState('2025-12-10');

// Get events for specific date
const todayEvents = events.filter(e => e.date === selectedDate);

// Get events in date range
const rangeEvents = events.filter(e =>
e.date >= '2025-12-01' && e.date <= '2025-12-31'
);
`

#### Bulk Operations

`jsx
// Change all event colors
const changeAllColors = (newColor) => {
setEvents(events.map(e => ({ ...e, color: newColor })));
};

// Shift all events by 1 hour
const shiftEvents = () => {
setEvents(events.map(e => ({
...e,
startTime: addHour(e.startTime),
endTime: addHour(e.endTime)
})));
};

// Delete events by criteria
const deletePastEvents = () => {
const today = new Date().toISOString().split('T')[0];
setEvents(events.filter(e => e.date >= today));
};
`

$3

`jsx
// Track date changes
const [date, setDate] = useState(null);

useEffect(() => {
if (date) {
console.log('Date changed to:', date);
// Trigger API call, validation, etc.
}
}, [date]);

// Track event changes
const [events, setEvents] = useState([]);

useEffect(() => {
console.log('Events updated:', events.length);
// Save to localStorage, sync with backend, etc.
localStorage.setItem('events', JSON.stringify(events));
}, [events]);
`

$3

`jsx
function App() {
const [events, setEvents] = useState([]);
const [selectedDate, setSelectedDate] = useState(null);

// Add event via button
const addQuickEvent = () => {
setEvents([...events, {
id: Date.now(),
date: new Date().toISOString().split('T')[0],
startTime: '09:00',
endTime: '10:00',
title: 'Quick Event',
color: '#10b981'
}]);
};

// Jump to specific date
const jumpToDate = (dateStr) => {
setSelectedDate(dateStr);
};

// Export events
const exportEvents = () => {
const json = JSON.stringify(events, null, 2);
console.log(json);
// Download or send to API
};

// Import events
const importEvents = (jsonData) => {
setEvents(JSON.parse(jsonData));
};

return (

Add Event
jumpToDate('2025-12-25')}>Jump to Dec 25
Export

events={events}
onEventCreate={(e) => setEvents([...events, e])}
onEventUpdate={(e) => setEvents(events.map(ev => ev.id === e.id ? e : ev))}
onEventDelete={(e) => setEvents(events.filter(ev => ev.id !== e.id))}
/>

);
}
`

Examples

$3

`jsx
value={value}
onChange={setValue}
showTime={true}
minuteStep={15}
/>
`

$3

`jsx
value={value}
onChange={setValue}
showTime={false}
/>
`

$3

`jsx
value={value}
onChange={setValue}
minDate="2025-01-01"
maxDate="2025-12-31"
/>
`

$3

`jsx
value={time}
onChange={setTime}
defaultValue="now"
minuteStep={15}
/>
`

$3

`jsx
value={value}
onChange={setValue}
showFooter={false}
/>
`

$3

`jsx
value={range}
onChange={setRange}
outputFormat="timestamp"
/>
`

$3

`jsx
events={events}
onEventCreate={handleCreate}
onEventUpdate={handleUpdate}
onEventDelete={handleDelete}
theme={{
primaryColor: '#ef4444',
headerBg: '#fee2e2',
eventRadius: '12px'
}}
/>
`

$3

`jsx
events={events}
onEventClick={handleClick}
editable={false}
/>
`

Mobile Support

All components are fully responsive and optimized for mobile devices:
- Touch-friendly interface with larger tap targets
- Adaptive layouts for small screens
- Centered modals on mobile
- Optimized spacing and font sizes
- Smooth scrolling within pickers

Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Opera (latest)
- Mobile browsers (iOS Safari, Chrome Mobile, Samsung Internet)

Persian Holiday Integration

All calendar components support Persian holiday integration via the Time.ir API:

`jsx



`

$3

- Automatic Loading: Holidays load automatically for the current month
- Visual Highlighting: Holiday dates appear with red background
- Read-Only: Holidays cannot be edited or deleted
- Clickable: Click holidays to see details
- API Integration: Uses Time.ir Persian calendar API with CORS proxy

License

MIT © BBBird1450

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

Support

For issues and questions:
- Open an issue on GitHub

Changelog

See CHANGELOG.md for release history.