vue-persian-calendar-datepicker

Vue Persian Calendar Date Picker

A comprehensive Vue 3 calendar and date picker component with support for Persian (Jalali), Hijri (Islamic), and Gregorian calendars

This is a Vue 3 component library providing full-featured calendar and date picker components with automatic conversions between three calendar systems. Display and select dates across Persian (Jalali), Hijri (Islamic), and Gregorian calendars simultaneously with comprehensive event management, smart theming, and extensive customization options.

Visualize date selection directly on the calendar using mouse interaction or programmatic control. The component includes over 300 Persian holidays and observances, Islamic religious events, and international world days with smart event indicators and detailed tooltips.

Features

• Triple Calendar System - Display Persian (Jalali), Hijri (Islamic), and Gregorian dates with automatic conversions
• Comprehensive Events - 300+ Persian holidays, Islamic events, and international observances with visual indicators
• Two Component Options - Full calendar view or compact datepicker with popup
• Fast Month & Year Selection - Jump directly to any month or a paged year range
• Date & Time Wheel Picker - Popup-free, one-unit mouse-wheel time controls
• Accessible by Default - Semantic buttons, keyboard navigation, ARIA labels, focus states, and reduced-motion support
• Advanced Theming - Light, dark, or auto-detection with per-color customization
• Date Range Control - Restrict selectable dates with from and to props
• Accurate Conversions - Precise Hijri conversion using lookup tables (1427-1464 AH)
• TypeScript Support - Complete type definitions for full IDE support
• Extensive Customization - 30+ slot-based customization points
• Responsive Design - Mobile-friendly with automatic popup positioning
• High Performance - Optimized rendering with computed properties
• Backward Compatible Date Model - Existing [year, month, day] values continue to work

Demo

Try the component interactively. The demo showcases calendar selection, datepicker interaction, custom theming, and comprehensive event management.

Quick Start

Installation

npm install vue-persian-calendar-datepicker

Basic Usage

<script setup>
import { PersianCalendar, PersianDatePicker } from 'vue-persian-calendar-datepicker'
</script>

<template>
  <!-- Full calendar -->
  <PersianCalendar />
  
  <!-- Compact date picker -->
  <PersianDatePicker v-model="date" />
</template>

Calendar Example

<script setup>
import { PersianCalendar } from 'vue-persian-calendar-datepicker'

const handleSelectDate = (event) => {
  console.log(event.date)        // [1403, 6, 15]
  console.log(event.events)      // { persianEvents: [...], hijriEvents: [...], ... }
}
</script>

<template>
  <PersianCalendar
    theme="dark"
    @select-date="handleSelectDate"
  />
</template>

Date Picker Example

<script setup>
import { ref } from 'vue'
import { PersianDatePicker } from 'vue-persian-calendar-datepicker'

const selectedDate = ref(null)

const handleDateChange = (date) => {
  console.log('Date changed:', date)
}
</script>

<template>
  <PersianDatePicker
    v-model="selectedDate"
    format="text"
    @change="handleDateChange"
  />
</template>

Date & Time Picker

Time selection is opt-in. Date-only usage still emits [year, month, day]; enabling time emits [year, month, day, hour, minute], or a sixth second value when seconds are enabled.

<script setup lang="ts">
import { ref } from 'vue'
import { PersianDatePicker } from 'vue-persian-calendar-datepicker'
import type { PersianDateTime } from 'vue-persian-calendar-datepicker'

const appointment = ref<PersianDateTime | null>(null)
</script>

<template>
  <PersianDatePicker
    v-model="appointment"
    enable-time
    enable-seconds
    format="YYYY/MM/DD HH:mm:ss"
  />
</template>

When time is enabled, choosing a day updates a draft. Move the pointer over the hour, minute, or second column and use the mouse wheel to change it one unit at a time, then press تأیید. The time control never opens a native select/dropdown. Arrow Up/Down remain available for keyboard accessibility, and closing the popup does not overwrite the current model.

Fast Month and Year Navigation

The month and year labels in both components are buttons. Clicking the month opens all 12 Persian months; clicking the year opens a paged year grid. Navigation automatically respects from, to, min-year, and max-year.

<PersianDatePicker
  v-model="date"
  :from="[1400, 1, 1]"
  :to="[1410, 12, 29]"
  :min-year="1390"
  :max-year="1420"
/>

Public Value Types

type PersianDate = [year: number, month: number, day: number]
type PersianDateTime = [year: number, month: number, day: number, hour: number, minute: number, second?: number]
type PersianDateValue = PersianDate | PersianDateTime

The picker accepts Latin, Persian, and Arabic digits in string values. Emitted v-model values are always typed numeric arrays.

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Accurate Date Conversions

The component uses precise conversion algorithms:

• Jalali to Gregorian: Accurate for all historical and future dates
• Jalali to Hijri: Uses lookup tables for years 1427-1464 AH with fallback calculations
• Gregorian to Jalali: Reverse conversion with high precision

Event Categories

The calendar displays:

• Persian Events: 100+ official and commemorative days (رویدادهای ایرانی)
• Hijri Events: 50+ Islamic religious events (رویدادهای اسلامی)
• World Events: 200+ international observances (رویدادهای جهانی)

License

MIT License - see LICENSE file for details

Contributing

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

Steps to contribute:

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

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Need help? Check the Documentation or review the Examples.

Credits

Built with Vue 3 and TypeScript for the Persian-speaking community and beyond.