yazdi-datepicker

v1.1.1

Published

6 months ago

A lightweight, accurate, and zero-dependency Persian (Jalali/Shamsi) calendar date picker with accurate date conversion and intuitive year/month selection flow

Yazdi DatePicker

A lightweight, accurate, and zero-dependency Persian (Jalali/Shamsi) calendar date picker with accurate date conversion and intuitive year/month selection flow.

Features

✨ Zero Dependencies - No external libraries required 📅 Accurate Date Conversion - Precise Gregorian to Jalali conversion 🎨 Beautiful UI - Modern and user-friendly interface 🔄 Smart Selection Flow - Intuitive year → month → day selection 🔢 Persian Numerals - Optional Persian number display 📱 Mobile Friendly - Responsive design for all devices ⚡ Lightweight - ~12KB minified 🌐 Universal - Works with all modern browsers 🎯 Smart Positioning - Calendar auto-positions to stay in viewport

Installation

Using npm

npm install yazdi-datepicker

Using a CDN

<!-- Development version -->
<script src="https://cdn.jsdelivr.net/npm/yazdi-datepicker/yazdi-datepicker.js"></script>

<!-- Production version (minified) -->
<script src="https://cdn.jsdelivr.net/npm/yazdi-datepicker/yazdi-datepicker.min.js"></script>

Direct Download

Download the latest release from GitHub and include it in your project:

<script src="path/to/yazdi-datepicker.min.js"></script>

Quick Start

HTML

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
    <meta charset="UTF-8">
    <title>Yazdi DatePicker Example</title>
</head>
<body>
    <input type="text" id="myDatePicker" placeholder="انتخاب تاریخ">

    <script src="yazdi-datepicker.min.js"></script>
    <script>
        const picker = new YazdiDatePicker('#myDatePicker');
    </script>
</body>
</html>

JavaScript (ES6 Modules)

import YazdiDatePicker from 'yazdi-datepicker';

const picker = new YazdiDatePicker('#myDatePicker', {
    format: 'YYYY/MM/DD',
    onSelect: (date) => {
        console.log('Selected date:', date);
    }
});

Node.js / CommonJS

const YazdiDatePicker = require('yazdi-datepicker');

const picker = new YazdiDatePicker('#myDatePicker');

API

Constructor

new YazdiDatePicker(inputElement, options)

Parameters

inputElement {string|HTMLElement} - CSS selector or DOM element
options {Object} - Configuration options (optional)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | format | string | 'YYYY/MM/DD' | Date format string | | onSelect | function | null | Callback function when date is selected | | autoClose | boolean | true | Auto-close calendar after date selection |

Methods

`setValue(dateString)`

Set the datepicker value programmatically.

picker.setValue('1403/07/15');

`getValue()`

Get the current value of the datepicker.

const currentDate = picker.getValue();
console.log(currentDate); // "1403/07/15"

`show()`

Programmatically show the calendar.

picker.show();

`hide()`

Programmatically hide the calendar.

picker.hide();

`destroy()`

Destroy the datepicker instance and remove all event listeners.

picker.destroy();

Examples

Basic Usage

const picker = new YazdiDatePicker('#birthDate');

With Callback Function

const picker = new YazdiDatePicker('#appointmentDate', {
    onSelect: function(date) {
        console.log('Appointment scheduled for:', date);
        // Send to server, update UI, etc.
    }
});

Custom Date Format

const picker = new YazdiDatePicker('#customDate', {
    format: 'YYYY-MM-DD',
    onSelect: (date) => {
        document.getElementById('output').textContent = date;
    }
});

Keep Calendar Open After Selection

const picker = new YazdiDatePicker('#dateInput', {
    autoClose: false
});

Multiple Date Pickers

const birthDate = new YazdiDatePicker('#birthDate', {
    format: 'YYYY/MM/DD'
});

const appointmentDate = new YazdiDatePicker('#appointmentDate', {
    format: 'YYYY-MM-DD',
    onSelect: (date) => alert('Date selected: ' + date)
});

Set Initial Value

const picker = new YazdiDatePicker('#dateInput');
picker.setValue('1403/01/01');

Dynamic Interaction

const picker = new YazdiDatePicker('#dateInput', {
    onSelect: function(date) {
        // Get Jalali date components
        const parts = date.split('/');
        const year = parts[0];
        const month = parts[1];
        const day = parts[2];

        console.log(`Selected: Day ${day}, Month ${month}, Year ${year}`);
    }
});

// Later in your code
document.getElementById('showBtn').addEventListener('click', () => {
    picker.show();
});

document.getElementById('resetBtn').addEventListener('click', () => {
    picker.setValue('');
});

Date Formats

The format option supports the following tokens:

| Token | Description | Example | |-------|-------------|---------| | YYYY | 4-digit year | 1403 | | MM | 2-digit month | 01 to 12 | | DD | 2-digit day | 01 to 31 |

Format Examples

YYYY/MM/DD → 1403/07/15 (default)
YYYY-MM-DD → 1403-07-15
DD/MM/YYYY → 15/07/1403

Browser Support

Yazdi DatePicker works in all modern browsers:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Opera (latest)
Mobile browsers (iOS Safari, Chrome Mobile, etc.)

Advanced Features

Leap Year Support

The datepicker accurately handles Jalali leap years using the 128-year cycle algorithm.

// Automatically handles leap years
// Esfand will show 30 days in leap years

Smart Calendar Positioning

The calendar automatically positions itself to stay within the viewport:

Opens below the input by default
Opens above if no space below
Adjusts horizontally to stay on screen
Accounts for scrolling

Persian Number Display

Month and year names are displayed in Persian, with Persian numerals:

// Displays: فروردین ۱۴۰۳

Intuitive Selection Flow

User-friendly selection process:

Click on year → Select year from grid
Automatically switches to month selector
Click on month → View calendar
Click on day → Date selected

Development

Building from Source

# Clone the repository
git clone https://github.com/maminyazdi/yazdi-datepicker.git
cd yazdi-datepicker

# Install dependencies
npm install

# Build minified version
npm run build

File Structure

yazdi-datepicker/
├── yazdi-datepicker.js        # Source file
├── yazdi-datepicker.min.js    # Minified production build
├── package.json
├── README.md
├── LICENSE
├── CHANGELOG.md
└── example.html               # Examples and demos

Examples

See example.html for a complete working demo with multiple use cases.

# Open example.html in your browser
open example.html

Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Amin Yazdi

GitHub: @maminyazdi
npm: yazdi-datepicker

Changelog

See CHANGELOG.md for a list of changes.

Support

🐛 Bug Reports: GitHub Issues
💬 Questions: GitHub Discussions
📧 Email: Contact via GitHub

Acknowledgments

Based on accurate Jalali calendar conversion algorithms
Inspired by the need for a lightweight, dependency-free Persian datepicker
Built with love for the Persian-speaking developer community

Made with ❤️ for Persian developers

If you find this useful, please ⭐ star the repository on GitHub!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Yazdi DatePicker

Features

Installation

Using npm

Using a CDN

Direct Download

Quick Start

HTML

JavaScript (ES6 Modules)

Node.js / CommonJS

API

Constructor

Parameters

Options

Methods

setValue(dateString)

getValue()

show()

hide()

destroy()

Examples

Basic Usage

With Callback Function

Custom Date Format

Keep Calendar Open After Selection

Multiple Date Pickers

Set Initial Value

Dynamic Interaction

Date Formats

Format Examples

Browser Support

Advanced Features

Leap Year Support

Smart Calendar Positioning

Persian Number Display

Intuitive Selection Flow

Development

Building from Source

File Structure

Examples

Contributing

License

Author

Changelog

Support

Acknowledgments

`setValue(dateString)`

`getValue()`

`show()`

`hide()`

`destroy()`