vue-jalali-datetime-picker

A powerful, simple, and customizable Jalali date and time picker for Vue.js and Nuxt applications. This package provides a flexible Jalali calendar component, enabling users to select single dates, date and time, multiple dates, or date ranges with ease. It supports custom theming, slot-based custom inputs, and is optimized for seamless integration into both modern Vue.js and Nuxt projects.

Enhance your Vue.js or Nuxt application with this Vue Jalali date picker for a robust and localized date selection experience, perfect for Persian (Farsi) users or applications requiring Jalali calendar support.

Features

• Single Date Picker: Select a single date using the Jalali calendar.
• Date and Time Picker: Choose both date and time for precise selection.
• Multiple Date Picker: Pick multiple dates effortlessly.
• Date Range Picker: Select a range of dates for flexible use cases.
• Customizable Themes: Customize colors via HSL or specific color values.
• Custom Input Support: Use custom input fields via Vue slots.
• Jalali Calendar Support: Tailored for Persian users with full Jalali date support.
• Teleport Support: Render modals outside the component hierarchy to avoid stacking context issues.
• Nuxt Compatibility: Fully compatible with Nuxt for server-side rendering and static site generation.

Installation

Getting started is easy! Choose your preferred package manager and run the following command to add vue-jalali-datetime-picker to your Vue.js or Nuxt project:

# Install with npm (great for Node.js projects)
npm i vue-jalali-datetime-picker

# Install with yarn (if you love speed and simplicity)
yarn add vue-jalali-datetime-picker

# Install with pnpm (perfect for efficient dependency management)
pnpm add vue-jalali-datetime-picker

Using a CDN

For quick testing or development without a build step, include the package via a CDN (e.g., unpkg). Add the following script tag to your HTML:

<script src="https://unpkg.com/vue-jalali-datetime-picker@latest/dist/vue-jalali-datetime-picker.umd.js"></script>

Usage

Below are examples demonstrating how to use the JalaliDateTimePicker and JalaliMultipleDatePicker components in your Vue.js or Nuxt application. Ensure you import the styles for proper rendering.

Importing Styles

• For Vue Projects: Import the CSS in your component:

  <script setup lang="ts">
  import "vue-jalali-datetime-picker/style.css";
  </script>

• For Nuxt Projects: Add the CSS to your nuxt.config.ts:

  // nuxt.config.ts
  export default defineNuxtConfig({
    css: ["vue-jalali-datetime-picker/style.css"],
  });

Importing the Components

Import the components into your Vue.js or Nuxt component:

<script setup lang="ts">
import { JalaliDateTimePicker, JalaliMultipleDatePicker } from "vue-jalali-datetime-picker";
</script>

Example 1: Simple Date Picker

Use the JalaliDateTimePicker for selecting a single date.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate = ref<Date | null>(null);
</script>

<template>
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ" />
</template>

Example 2: Date and Time Picker

Enable time selection by adding the enable-time prop.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDateAndTime = ref<Date | null>(null);
</script>

<template>
  <JalaliDateTimePicker v-model:date="selectedDateAndTime" label="انتخاب تاریخ و زمان" enable-time />
</template>

Example 3: Using the format Prop

Specify the format of the returned value using the format prop.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate = ref<Date | null>(null);
</script>

<template>
  <!-- Return only the date -->
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ" :format="'date'" />

  <!-- Return date and time -->
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ و زمان" enable-time :format="'datetime'" />
</template>

Example 4: Multiple Dates Picker

Use JalaliMultipleDatePicker to select multiple dates.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliMultipleDatePicker } from "vue-jalali-datetime-picker";

const selectedManyDates = ref<Date[]>([]);
</script>

<template>
  <JalaliMultipleDatePicker v-model:dates="selectedManyDates" label="انتخاب چندین تاریخ" type="multiple" />
</template>

Example 5: Ranged Dates Picker

Select a range of dates using the range type.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliMultipleDatePicker } from "vue-jalali-datetime-picker";

const selectedPeriodOfDates = ref<Date[]>([]);
</script>

<template>
  <JalaliMultipleDatePicker v-model:dates="selectedPeriodOfDates" label="انتخاب بازه ای از تاریخ ها" type="range" />
</template>

Example 6: Using Teleport for Modal Rendering

The teleportTo prop allows you to render the calendar modal outside the component's DOM hierarchy, solving z-index and stacking context issues in complex layouts.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate = ref<Date | null>(null);
</script>

<template>
  <!-- Teleport to body (recommended for most cases) -->
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ" teleport-to="body" />

  <!-- Teleport to a custom element -->
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ" teleport-to="#modal-container" />

  <!-- Without teleport (default behavior) -->
  <JalaliDateTimePicker v-model:date="selectedDate" label="انتخاب تاریخ" />
</template>

When to use teleportTo:

• When the picker is inside elements with overflow: hidden or position: relative
• When you need the modal to appear above other overlays or fixed elements
• When experiencing z-index conflicts in production environments

Customizing Colors

You can customize the calendar's appearance in two ways:

Option 1: HSL-Based Theming

Provide HSL values to automatically generate primaryHover, primaryActive, and primaryLight colors.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate2 = ref<Date | null>(null);
</script>

<template>
  <JalaliDateTimePicker
    v-model:date="selectedDate2"
    label="تقویم با تم کاستوم"
    :theme="{
      primaryH: '300',
      primaryS: '70%',
      primaryL: '45%',
      textPrimary: 'black',
      textSecondary: 'white',
    }"
  />
</template>

Option 2: Specific Color Values

Set specific color values for full control.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate2 = ref<Date | null>(null);
</script>

<template>
  <JalaliDateTimePicker
    v-model:date="selectedDate2"
    label="تقویم با تم کاستوم"
    :theme="{
      primary: '#3b82f6',
      primaryHover: '#2563eb',
      primaryActive: '#1d4ed8',
      primaryLight: '#93c5fd',
    }"
  />
</template>

Custom Input with Slots

Customize the input field using Vue slots for a tailored user experience.

<script setup lang="ts">
import { ref } from "vue";
import { JalaliDateTimePicker } from "vue-jalali-datetime-picker";

const selectedDate3 = ref<Date | null>(null);
</script>

<template>
  <JalaliDateTimePicker v-model:date="selectedDate3" label="انتخاب تاریخ با فیلد کاستوم">
    <template #input="{ label, elementId, formattedDate, setShowCalender, clearDate }">
      <div>
        <label
          v-if="label"
          :for="elementId"
          style="
            display: block;
            margin-bottom: 6px;
            font-size: 14px;
            color: #333;
            font-weight: 500;
          "
        >
          {{ label }}
        </label>

        <div
          @click="setShowCalender(true)"
          style="
            display: flex;
            align-items: center;
            justify-content: space-between;
            border: 1px solid #ccc;
            border-radius: 6px;
            padding: 8px 10px;
            font-size: 14px;
            color: #333;
            background: #fff;
            cursor: pointer;
            min-height: 36px;
          "
        >
          <span style="flex: 1; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">
            {{ formattedDate || "—" }}
          </span>

          <button
            v-if="formattedDate"
            @click.stop="clearDate"
            style="
              background: none;
              border: none;
              color: #888;
              cursor: pointer;
              padding: 2px 4px;
              font-size: 14px;
            "
          >
            ❌
          </button>
        </div>
      </div>
    </template>
  </JalaliDateTimePicker>
</template>

Feedback and Contributions

If you encounter any bugs or have suggestions for improvements, please share them in the GitHub Issues section of our repository. We welcome your feedback to make this Vue Jalali date picker even better!

Built With

• Vue.js - The Progressive JavaScript Framework
• jalaali-js - A library for working with Jalali (Persian) calendar dates

License

This project is licensed under the MIT License.