@mahlaparvaz/vue-datepicker

---

🎯 Why Choose This Datepicker?

- 🌍 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

---

✨ Features

$3

- ✅ Single Date: Pick one date
- ✅ Range Selection: Start and end dates with visual indicators
- ✅ Multiple Dates: Select multiple non-consecutive dates

$3

- 🗓️ Jalali (Persian/Shamsi): Full support for Persian calendar
- 🗓️ Gregorian: Standard international calendar
- 🗓️ Hijri (Islamic): Lunar Islamic calendar
- 🗓️ Chinese: Traditional Chinese calendar

$3

- ⏰ 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

---

📦 Installation

``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
`

$3

This package requires:

- vue ^3.5.0
- vue-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

---

🚀 Quick Start

$3

`vue



`

$3

`vue



`

$3

`vue



`

$3

`vue



`

---

📖 Documentation

$3

| 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 |

---

🎨 Customization

$3

`vue
:theme="{
colors: {
primary: '#e91e63',
primaryHover: '#c2185b',
textPrimary: '#ffffff',
background: '#1a1a1a',
},
dimensions: {
inputHeight: '48px',
borderRadius: '12px',
},
spacing: {
padding: '16px',
},
}"
>


`

$3

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 /
}
`

$3

`vue
:font-config="{
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"
/>
`

---

💡 Examples

$3

`vue



`

$3

`vue
locale="jalali"
:font-config="{ jalali: 'Vazir' }"
:theme="{
colors: {
primary: '#059669',
primaryHover: '#047857',
},
}"
v-model="persianDate"
>


`

$3

`vue



`

$3

`vue



`

$3

`vue



`

---

🌐 Internationalization

$3

- jalali - Persian/Farsi (فارسی) - RTL
- gregorian - English - LTR
- hijri - Arabic (العربية) - RTL
- chinese - Chinese (中文) - LTR

$3

`vue



`

---

🔧 Utility Functions

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
`

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

$3

`bash


Install dependencies

npm install

Start development server

npm run dev

Build library

npm run build

Lint code

npm run lint

Format code

npm run format
``

---

📝 Changelog

See CHANGELOG.md for detailed release notes.

📄 License

MIT © Mahla Zohourparvaz

---

💬 Support

- 📧 Email: mahla.zph@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions

---

🌟 Show Your Support

If this package helps you, please give it a ⭐️ on GitHub!

---