Jalali Date Picker (Vue 3)

A lightweight, dependency‑minimal Jalali (Persian) date picker for Vue 3.

The component stores dates internally as Gregorian ISO (YYYY‑MM‑DD) for backend sanity, while displaying Jalali dates with Persian digits in the UI.

This separation of concerns keeps both humans and databases happy.

✨ Highlights

• 🇮🇷 Native Jalali (Shamsi) calendar with Persian month names

• 🔁 Gregorian ISO storage (API & DB friendly)

• 🎛 Fully configurable v-model output

• 🧠 Smart input parsing (mixed separators + Persian digits)

• 📐 Full RTL & LTR layout support

• 📅 Saturday‑first week (Iran standard)

• 🧩 Headless‑friendly (slot‑based icon)

• 🪶 Zero heavy date libraries

🧱 Built With

| Tool | Purpose | | --- | --- | | Vue 3 | Composition API (<script setup>) | | jalaali-js | Jalali ↔ Gregorian conversion | | Plain CSS | No UI framework |

📦 Installation

npm install vue-jalali-date-input

🚀 Basic Usage

<script setup>
import { ref } from "vue";
import { JalaliInput } from "vue-jalali-date-input";

const date = ref("");
</script>

<template>
  <JalaliInput v-model="date" />
</template>

Result

| UI Display | Stored Value (date.value) | | --- | --- | | ۱۴۰۳/۰۷/۰۳ | 2024-09-24 |

🧠 v-model Behavior (Important)

Internally, everything is Gregorian ISO:

YYYY-MM-DD

This design:

• Avoids timezone bugs

• Prevents backend ambiguity

• Eliminates locale‑dependent parsing

• Reduces existential dread

You control what v-model represents and emits via props.

⚙️ Props

v-model

| Type | Description | | --- | --- | | string | Selected date value |

Accepted Input Formats:

• YYYY-MM-DD

• YYYY/MM/DD

• YYYY.MM.DD

• Persian digits (۱۴۰۳/۰۷/۰۳)

valueType

Controls which calendar the v-model represents.

| Type | Default | | --- | --- | | `"gregorian" | "jalali"` |

<JalaliInput v-model="date" valueType="gregorian" />

valueFormat

Controls the output format of v-model.

| Type | Default | | --- | --- | | string | YYYY-MM-DD |

Supported Patterns:

| Pattern | | --- | | YYYY-MM-DD | | YYYY/MM/DD | | YYYY.MM.DD | | YYYY MM DD |

<JalaliInput
  v-model="date"
  valueType="jalali"
  valueFormat="YYYY/MM/DD"
/>

placeholder

| Type | Default | | --- | --- | | string | انتخاب تاریخ |

digits

Controls digits used in v-model output.

| Value | Description | | --- | --- | | en | English digits | | fa | Persian digits |

Default: en

<JalaliInput v-model="date" digits="fa" />

Output:

۱۴۰۳/۰۷/۰۳

footer

Shows footer action buttons.

| Type | Default | | --- | --- | | boolean | false |

Footer Actions:

| Label | Action | | --- | --- | | امروز | Select today | | پاک کردن | Clear value |

dir

Controls layout direction.

| Value | Default | | --- | --- | | `rtl | ltr` |

Automatically adjusts:

• Input padding

• Popover alignment

🧩 Slots

icon

Override the calendar icon.

<JalaliInput>
  <template #icon>
    <MyCustomIcon />
  </template>
</JalaliInput>

📡 Events

| Event | Description | | --- | --- | | update:modelValue | Standard Vue v-model update |

⌨️ Keyboard & Mouse Behavior

| Interaction | Behavior | | --- | --- | | Input | Readonly (prevents manual corruption) | | Click input / icon | Opens calendar | | Click outside | Closes calendar | | Select date | Closes calendar | | Clear | Emits empty string |

🏗 Internal Design (Why This Works)

| Principle | Outcome | | --- | --- | | Single source of truth | Predictable state | | Gregorian core | Backend‑safe | | Conversion at edges only | Fewer bugs | | No Date mutation | SSR‑safe |

Resulting in a component that is:

• Backend‑friendly

• SSR‑safe

• Testable

• Deterministic

🎨 Styling

• All styles are scoped

• No framework assumptions

You can override styles via:

• Wrapping selectors

• CSS variables (recommended for extension)

📋 Requirements

| Dependency | Version | | --- | --- | | Vue | 3.3+ | | jalaali-js | Latest |

⚠️ Known Limitations

| Limitation | Reason | | --- | --- | | No time selection | Intentional simplicity | | Day‑level precision only | Avoids ambiguity | | Persian UI only | By design |

📄 License

MIT License

Copyright (c) 2025 Ahmed Ahmedpour

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.