Vue 3 datepicker supporting Jalali, Hijri, Gregorian, Chinese calendars with range, time picker, i18n, RTL, and full customization.
npm install @mahlaparvaz/vue-datepicker



A powerful, lightweight Vue 3 datepicker with multi-calendar support
Features • Installation • Quick Start • Documentation • Examples
---
- 🌍 Multi-Calendar Support: Jalali (Persian), Gregorian, Hijri (Islamic), and Chinese calendars out of the box
- 🎨 Headless Architecture: Complete UI control with scoped slots - build your own design
- 📦 Lightweight: Only ~18KB gzipped after peer dependency optimization
- 🔧 Fully Customizable: 70+ CSS variables, theme props, and custom fonts per calendar
- ♿ Accessible: WCAG compliant with keyboard navigation and ARIA labels
- 🌐 i18n Ready: Built-in internationalization with RTL/LTR support
- ⚡ Zero Config: Automatic CSS injection, no manual imports needed
- 📱 Responsive: Mobile-optimized with touch support
---
- ✅ Single Date: Pick one date
- ✅ Range Selection: Start and end dates with visual indicators
- ✅ Multiple Dates: Select multiple non-consecutive dates
- 🗓️ Jalali (Persian/Shamsi): Full support for Persian calendar
- 🗓️ Gregorian: Standard international calendar
- 🗓️ Hijri (Islamic): Lunar Islamic calendar
- 🗓️ Chinese: Traditional Chinese calendar
- ⏰ Time Picker: Optional 12/24-hour time selection
- 🎨 Theming: CSS variables + theme prop with dark mode support
- 🔤 Custom Fonts: Configure fonts per calendar type
- 📅 Date Constraints: Min/max dates, year range limits
- 🔄 Output Formats: Object, timestamp, unix, ISO, custom string, or function
- 💾 Locale Persistence: Remembers user's calendar preference
- ⌨️ Keyboard Navigation: Full keyboard support
- 📱 Mobile Friendly: Responsive overlay with touch gestures
- ♿ High Contrast: Accessibility features built-in
---
``bash`
npm install @mahlaparvaz/vue-datepicker vue-i18n @vueuse/core
`bash`
yarn add @mahlaparvaz/vue-datepicker vue-i18n @vueuse/core
`bash`
pnpm add @mahlaparvaz/vue-datepicker vue-i18n @vueuse/core
This package requires:
- vue ^3.5.0vue-i18n
- ^10.0.0 || ^11.0.0 || ^12.0.0-alpha.3@vueuse/core
- ^10.0.0 || ^11.0.0 || ^12.0.0 || ^13.0.0 || ^14.0.0
---
`vue
`
`vue
`
`vue`
:value="formattedDate"
@click="open"
placeholder="Select date and time"
readonly
/>
`vue`
:value="formattedDate"
@click="open"
placeholder="Select date (Jalali/Gregorian only)"
readonly
/>
---
| Prop | Type | Default | Description |
| -------------------- | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- |
| modelValue | Object \| Array \| null | null | Selected date(s) - use with v-model |mode
| | 'single' \| 'range' \| 'multiple' | 'single' | Selection mode |locale
| | String | User's saved locale | Calendar locale: 'jalali', 'gregorian', 'hijri', 'chinese' |availableLocales
| | Array | ['jalali', 'gregorian', 'hijri', 'chinese'] | Available calendar types in locale selector |placeholder
| | String | Auto-generated | Input placeholder text |format
| | String | 'YYYY/MM/DD' | Display format for dates |outputFormat
| | String \| Function | 'object' | Output format: 'object', 'timestamp', 'unix', 'iso', 'string', or custom function |outputStringFormat
| | String | 'YYYY/MM/DD' | String format when outputFormat="string" |enableTime
| | Boolean | false | Enable time selection |timeFormat
| | Number \| String | 24 | Time format: 12 or 24 |yearsBefore
| | Number | 50 | Years to show before current year |yearsAfter
| | Number | 50 | Years to show after current year |minDate
| | Date \| String \| Object | null | Minimum selectable date |maxDate
| | Date \| String \| Object | null | Maximum selectable date |disabled
| | Boolean | false | Disable the datepicker |fontConfig
| | Object | null | Custom fonts per calendar: { jalali: 'Vazir', gregorian: 'Roboto' } |theme
| | Object | null | Theme configuration object |closeOnSelect
| | Boolean | true | Close picker after selection (single mode only) |autoApply
| | Boolean | false | Auto-apply selection without confirm button |
---
`vue`
colors: {
primary: '#e91e63',
primaryHover: '#c2185b',
textPrimary: '#ffffff',
background: '#1a1a1a',
},
dimensions: {
inputHeight: '48px',
borderRadius: '12px',
},
spacing: {
padding: '16px',
},
}"
>
Override globally in your CSS:
`css`
:root {
--datepicker-primary-500: #3b82f6;
--datepicker-primary-600: #2563eb;
--datepicker-gray-50: #f9fafb;
--datepicker-gray-900: #111827;
--datepicker-border-radius: 8px;
--datepicker-font-size-base: 14px;
/ ...70+ more variables available /
}
`vue`
jalali: 'Vazir, sans-serif',
gregorian: 'Roboto, sans-serif',
hijri: 'Noto Naskh Arabic, serif',
chinese: 'Noto Sans SC, sans-serif',
}"
>
Load fonts via CDN or npm:
`html`
href="https://fonts.googleapis.com/css2?family=Vazir&family=Roboto&display=swap"
rel="stylesheet"
/>
---
`vue
`
`vue`
:font-config="{ jalali: 'Vazir' }"
:theme="{
colors: {
primary: '#059669',
primaryHover: '#047857',
},
}"
v-model="persianDate"
>
:value="formattedDate"
:style="{ fontFamily }"
@click="open"
placeholder="تاریخ را انتخاب کنید"
dir="rtl"
readonly
/>
`vue
mode="range"
:enable-time="true"
:min-date="today"
:max-date="maxDate"
output-format="iso"
>
{{ formattedDate || 'Select booking period' }}
`
`vue
`
`vue
`
---
- jalali - Persian/Farsi (فارسی) - RTLgregorian
- - English - LTRhijri
- - Arabic (العربية) - RTLchinese
- - Chinese (中文) - LTR
`vue
`
---
Export and use validation utilities:
`javascript
import {
isValidJalaaliDate,
isValidGregorianDate,
isValidDate,
parseDate,
} from '@mahlaparvaz/vue-datepicker';
// Validate Jalali date
isValidJalaaliDate(1403, 9, 15); // true
// Validate Gregorian date
isValidGregorianDate(2024, 2, 29); // true (leap year)
// Parse date strings
const parsed = parseDate('1403/09/15');
// { jy: 1403, jm: 9, jd: 15 }
// Universal date validation
isValidDate({ year: 2024, month: 12, day: 16 }); // true
`
---
Contributions are welcome! Please follow these steps:
1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'
3. Commit your changes: git push origin feature/amazing-feature
4. Push to the branch:
5. Open a Pull Request
`bashInstall dependencies
npm install
---
See CHANGELOG.md for detailed release notes.
MIT © Mahla Zohourparvaz
---
- 📧 Email: mahla.zph@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
---
If this package helps you, please give it a ⭐️ on GitHub!
---
Made with ❤️ for the Vue community