svelte-persian-datepicker Svelte Themes

Svelte Persian Datepicker

Persian DatePicker for Svelte5 (icnludes many features: multi selection and range selection, multi calendar, highly customizable)

Persian DatePicker Component (Svelte 5)

๐ŸŒŸ Live Demo ๐ŸŒŸ

A highly customizable and feature-rich date picker component built with Svelte 5, supporting Persian (Jalali), Gregorian, and Arabic calendars. This component is inspired by and converted from Alireza's Vue3 Persian DatePicker.

โœจ Features

๐Ÿ“… Selection Modes

  • Single Date: Select one date
  • Date Range: Select from one date to another
  • Multiple Dates: Select multiple individual dates (click to toggle)
  • Time Only: Select time without date
  • DateTime: Select both date and time
  • DateTime Range: Select from one datetime to another datetime

๐ŸŒ Localization & Calendar Support

  • Persian (Jalali): Full support for Persian calendar
  • Gregorian: Standard international calendar
  • Arabic: Arabic calendar support
  • RTL/LTR: Automatic direction support based on locale

๐ŸŽจ Customization

  • Colors: Multiple color themes (blue, red, pink, orange, green, purple, gray)
  • Formats: Customizable display formats, input formats
  • Styles: Full CSS customization support
  • Icons: Custom icon support
  • Shortcuts: Predefined shortcuts for quick selections

๐Ÿ’ก User Experience

  • Clearable Input: Option to clear selected dates
  • Auto Submit: Automatic submission on selection
  • Keyboard Navigation: Full keyboard support
  • Modal Mode: Can be displayed as modal
  • Dual Input: Separate inputs for range selection
  • Validation: Built-in date validation and disable rules

๐Ÿš€ Installation

npm install @hamedf/svelte-persian-datepicker
# or
pnpm install @hamedf/svelte-persian-datepicker
# or
yarn add @hamedf/svelte-persian-datepicker

๐Ÿ“– Basic Usage

<script>
  import DatePicker from '@hamedf/svelte-persian-datepicker';
  
  let selectedDate = '';
  
  function handleSubmit(date) {
    console.log('Selected date:', date);
  }
</script>

<DatePicker
  bind:model={selectedDate}
  mode="single"
  type="date"
  submit={handleSubmit}
  color="blue"
  clearable={true}
/>

๐ŸŽฏ Usage Examples

Single Date Selection

<DatePicker
  bind:model={singleDate}
  mode="single"
  type="date"
  submit={handleSingleDate}
  color="blue"
/>

Date Range Selection

<DatePicker
  bind:model={dateRange}
  mode="range"
  type="date"
  submit={handleDateRange}
  color="green"
/>

Multiple Date Selection

<DatePicker
  bind:model={multipleDates}
  mode="multiple"
  type="date"
  submit={handleMultipleDates}
  color="purple"
  auto_submit={false}
/>

Time Selection

<DatePicker
  bind:model={selectedTime}
  mode="single"
  type="time"
  input_format="HH:mm"
  submit={handleTime}
  color="orange"
/>

DateTime Selection

<DatePicker
  bind:model={selectedDateTime}
  mode="single"
  type="datetime"
  input_format="YYYY-MM-DD HH:mm"
  submit={handleDateTime}
  color="red"
/>

DateTime Range Selection

<DatePicker
  bind:model={dateTimeRange}
  mode="range"
  type="datetime"
  input_format="YYYY-MM-DD HH:mm"
  submit={handleDateTimeRange}
  color="pink"
/>

โš™๏ธ Props

Prop Type Default Description
model string | string[] | PersianDate | PersianDate[] undefined The selected value(s)
mode 'single' | 'range' | 'multiple' 'single' Selection mode
type 'date' | 'time' | 'datetime' 'date' Type of picker
format string undefined Output format
input_format string undefined Input format
display_format string undefined Display format
color 'blue' | 'red' | 'pink' | 'orange' | 'green' | 'purple' | 'gray' undefined Color theme
locale string 'fa' Locale (fa, en, ar)
clearable boolean true Show clear button
auto_submit boolean true Auto submit on selection
modal boolean false Display as modal
dual_input boolean false Separate inputs for range
shortcut boolean | object false Enable shortcuts
column number | object 1 Number of calendar columns
from string '1300' Minimum date/time
to string '1430' Maximum date/time
disable object undefined Disable rules

๐ŸŽจ Events

Event Parameters Description
submit date: PersianDate | PersianDate[] Fired when date is submitted
select date: PersianDate Fired when date is selected
clear none Fired when picker is cleared
open none Fired when picker opens
close none Fired when picker closes

๐ŸŽจ Styling

The component supports full CSS customization. You can override the default styles by targeting the component classes:

/* Custom styling for multiple selection */
:global(.pdp-multiple .pdp-day.selected) {
  background-color: #8b5cf6 !important;
  color: white !important;
  border-radius: 4px;
  font-weight: 600;
}

/* Custom range styling */
:global(.pdp-range .pdp-day.start-range) {
  background-color: your-color;
}

๐Ÿ”ง Development

Prerequisites

  • Node.js 18+
  • pnpm

Setup

# Clone the repository
git clone https://github.com/hamedf62/svelte-persian-datepicker

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

๐Ÿ“‚ Project Structure

src/
โ”œโ”€โ”€ lib/
โ”‚   โ”œโ”€โ”€ DatePicker.svelte          # Main component
โ”‚   โ”œโ”€โ”€ components/                # Sub-components
โ”‚   โ”‚   โ”œโ”€โ”€ PDPArrow.svelte
โ”‚   โ”‚   โ”œโ”€โ”€ PDPIcon.svelte
โ”‚   โ”‚   โ””โ”€โ”€ PDPAlt.svelte
โ”‚   โ”œโ”€โ”€ modules/
โ”‚   โ”‚   โ”œโ”€โ”€ core.ts               # Core logic
โ”‚   โ”‚   โ””โ”€โ”€ types.ts              # TypeScript types
โ”‚   โ””โ”€โ”€ assets/sass/              # Styles
โ””โ”€โ”€ routes/
    โ””โ”€โ”€ +page.svelte              # Demo page

๐Ÿงช Testing

The component includes comprehensive tests using Cypress:

# Run component tests
pnpm test:component

# Run e2e tests
pnpm test:e2e

# Open Cypress UI
pnpm cypress:open

๐Ÿ“„ Documentation

For detailed documentation and API reference, visit Alireza's Documentation as this component maintains compatibility with the original Vue3 version.

๐Ÿค Contributing

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

๐Ÿ“ License

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

๐Ÿ™ Acknowledgments

  • Alireza-ab for the original Vue3 Persian DatePicker
  • Persian calendar calculations and localization support
  • Svelte community for the amazing framework

๐Ÿ“Š Features Comparison

Feature Single Range Multiple Time DateTime DateTime Range
Select one date โœ… โŒ โŒ โŒ โœ… โŒ
Select date range โŒ โœ… โŒ โŒ โŒ โœ…
Select multiple dates โŒ โŒ โœ… โŒ โŒ โŒ
Time selection โŒ โŒ โŒ โœ… โœ… โœ…
Persian calendar โœ… โœ… โœ… โœ… โœ… โœ…
Keyboard navigation โœ… โœ… โœ… โœ… โœ… โœ…
Custom validation โœ… โœ… โœ… โœ… โœ… โœ…

๐Ÿค– AI/LLM Integration Guide

This component has been optimized for AI coding assistants and LLMs. Here's how to work with it effectively:

๐Ÿ“‹ Quick Reference for AI Agents

// COMPONENT SIGNATURE FOR AI REFERENCE
/**
 * @component PersianDatePicker
 * @description A comprehensive Svelte 5 Persian/Jalali DateTime picker
 * @props {Object} Props - See interface below for all available props
 * @bindable model - The selected date(s) value
 * @example
 * // Single date selection
 * <DatePicker bind:model={selectedDate} />
 * 
 * // Range selection  
 * <DatePicker mode="range" bind:model={dateRange} />
 * 
 * // Multiple dates
 * <DatePicker mode="multiple" bind:model={multipleDates} />
 * 
 * // With custom validation
 * <DatePicker 
 *   bind:model={date}
 *   from="1400/01/01" 
 *   to="1405/12/29"
 *   disable={['1403/01/01', '1403/05/15']}
 * />
 */

๐ŸŽฏ Common AI Prompts & Solutions

For Setting Up Basic Date Selection:

// AI: "Create a basic Persian date picker"
let selectedDate: string;

<DatePicker 
  bind:model={selectedDate}
  locale="fa"
  type="date"
  mode="single"
/>

For Range Selection:

// AI: "Create a date range picker for Persian calendar"
let dateRange: string[];

<DatePicker
  bind:model={dateRange}
  mode="range"
  locale="fa"
  dual_input={true}
/>

For Time Selection:

// AI: "Add time picker functionality"
let selectedTime: string;

<DatePicker
  bind:model={selectedTime}
  type="time"
  from="08:00"
  to="20:00"
/>

For Multi-Calendar Support:

// AI: "Support both Persian and Gregorian calendars"
let date: string;

<DatePicker
  bind:model={date}
  locale="fa,en"
  input_calendar="auto"
/>

๐Ÿ”ง Props Reference for AI

Essential Props for Common Use Cases:

  • bind:model - The selected date value(s) - ALWAYS BINDABLE
  • mode - Selection type: "single" | "range" | "multiple"
  • type - Picker type: "date" | "time" | "datetime"
  • locale - Language/calendar: "fa" | "en" | "ar" | "fa,en"
  • from/to - Date boundaries (e.g., "1400/01/01", "1405/12/29")
  • disable - Disabled dates/times (array, function, or regex)

Styling & UI Props:

  • color - Theme: "blue" | "red" | "pink" | "orange" | "green" | "purple" | "gray"
  • dual_input - Separate inputs for range mode
  • modal - Show as modal overlay
  • clearable - Show clear button

Advanced Props:

  • format - Model data format (always Gregorian)
  • input_format - Input parsing format
  • display_format - UI display format
  • input_calendar - Calendar for input: "auto" | "jalali" | "gregorian"

๐Ÿ’ก AI Best Practices

  1. Always use bind:model for data binding
  2. Check mode prop for selection behavior
  3. Use from/to props for date boundaries
  4. Use disable prop for validation rules
  5. Set locale appropriately for language/calendar
  6. Consider dual_input for better range UX

Top categories

Loading Svelte Themes