Persian Date and Time Pickers

A comprehensive package providing separate DatePicker and TimePicker components for Angular applications, with support for both Jalali (Persian) and Gregorian calendars. This package supports Angular 14 and above. Specific version compatibility:

Package Version	Angular Version
0.x.x	≥14.0.0

Demo

You can see the online Demo

Components

This package includes two main components:

1. PersianDatePicker: A flexible date picker with range selection support and time selection
2. PersianTimePicker: A standalone time picker with 12/24 hour format support

Features

DatePicker

• 📅 Support for both Jalali (Persian) and Gregorian calendars
• 🎯 Single date and date range selection
• ⏰ Integrated time selection support
• 🌐 Multilingual support (English/Persian)
• 📏 Min/Max date restrictions
• 🎨 Customizable styles
• 📱 Responsive design
• ⌨️ Keyboard navigation
• 🔄 Form integration
• 📋 Custom period labels
• 📐 Multiple placement options
• 🔄 Value format flexibility (string/Date object)
• 🎯 Today button support
• 🚫 Disabled dates support with custom filtering
• 🎨 Custom templates for days, months, and years
• 🔒 Read-only mode support

TimePicker

• ⏰ 12/24 hour format support
• ⏱️ Optional seconds display
• 🔒 Time range restrictions
• 🎭 Time input mask
• 🌐 Multilingual AM/PM
• 📍 Inline display mode
• 🔄 Date adapter integration
• 🚫 Disabled times support with custom filtering

Installation

1npm install @angular/cdk@<COMPATIBLE_VERSION> persian-date-time-picker

Dependencies

1{
2  "@angular/cdk": ">=14.0.0",
3  "date-fns": ">=4.1.0",
4  "date-fns-jalali": ">=4.1.0-0"
5}

Required Styles

1@import '@angular/cdk/overlay-prebuilt.css';

DatePicker Usage

Basic Usage

1// app.module.ts
2import {PersianDateTimePickerModule} from 'persian-date-time-picker';
3
4@NgModule({
5  imports: [PersianDateTimePickerModule]
6})
7export class AppModule {
8}
9
10// component.ts
11@Component({
12  template: `
13    <persian-date-picker 
14      [(ngModel)]="selectedDate"
15      [calendarType]="'jalali'">
16    </persian-date-picker>
17  `
18})
19export class AppComponent {
20  selectedDate: Date | string = '1403/01/01'; // Can accept both Date object and string
21}

Range Selection

The DatePicker supports flexible range selection with multiple ways to handle values:

1
2@Component({
3  template: `
4    <persian-date-picker
5      [(ngModel)]="dateRange"
6      [isRange]="true"
7      [rangeInputLabels]="{ start: 'From', end: 'To' }"
8      [emitInDateFormat]="false"
9      [calendarType]="'jalali'">
10    </persian-date-picker>
11  `
12})
13export class AppComponent {
14  // Using string values
15  dateRange = {
16    start: '1403/08/12',
17    end: '1403/08/15'
18  };
19
20  // Using mixed values (string and Date)
21  dateRange2 = {
22    start: '1403/08/12',
23    end: new Date()
24  };
25
26  // Using Date objects
27  dateRange3 = {
28    start: new Date('2024-01-01'),
29    end: new Date('2024-01-07')
30  };
31
32  // With emitInDateFormat=true, values will be emitted as Date objects
33  onRangeChange(range: { start: Date, end: Date }) {
34    console.log('Start:', range.start);
35    console.log('End:', range.end);
36  }
37}

Range Selection with Predefined Periods

1// Define custom period labels
2const customLabels: CustomLabels[] = [
3  {
4    label: 'This Week',
5    value: [new Date('2024-01-01'), new Date('2024-01-07')]
6  },
7  {
8    label: 'Last 7 Days',
9    value: ['1403/08/05', '1403/08/12'] // Can use strings for Jalali dates
10  },
11  {
12    label: 'Custom Range',
13    value: 'custom'
14  }
15];
16
17@Component({
18  template: `
19    <persian-date-picker
20      [(ngModel)]="dateRange"
21      [isRange]="true"
22      [customLabels]="customLabels"
23      (onChangeValue)="onRangeChange($event)">
24    </persian-date-picker>
25  `
26})

Date and Time Selection

1
2@Component({
3  template: `
4    <persian-date-picker 
5      [(ngModel)]="selectedDateTime"
6      [format]="'yyyy/MM/dd HH:mm:ss'"
7      [showTimePicker]="true"
8      [timeDisplayFormat]="'HH:mm'"
9      [showToday]="true">
10    </persian-date-picker>
11  `
12})
13export class AppComponent {
14  selectedDateTime: Date | string = new Date();
15}

Value Format Options

1@Component({
2  template: `
3    <persian-date-picker
4      [(ngModel)]="selectedDate"
5      [valueFormat]="'gregorian'"  // 'gregorian' | 'jalali' | 'date'
6      [calendarType]="'jalali'">
7    </persian-date-picker>
8  `
9})

Disabled Dates

1
2@Component({
3  template: `
4    <persian-date-picker
5      [(ngModel)]="selectedDate"
6      [disabledDates]="disabledDates"
7      [disabledDatesFilter]="disabledDatesFilter">
8    </persian-date-picker>
9  `
10})
11export class AppComponent {
12  // These will disable the entire day
13  disabledDates = [
14    new Date(2024, 0, 1),  // Jan 1, 2024
15    new Date(2024, 11, 25), // Dec 25, 2024
16    '2024/01/15'  // Jan 15, 2024
17  ];
18
19  // This will disable specific days advanced
20  disabledDatesFilter = (date: Date) => {
21    const day = date.getDay();
22    return day === 0 || day === 6; // Disable weekends
23  };
24}

Custom Templates

The DatePicker now supports custom templates for days, months, and years, allowing you to customize how these elements are rendered:

1
2@Component({
3  template: `
4    <persian-date-picker [(ngModel)]="selectedDate">
5      <!-- Custom day template -->
6      <ng-template dtp-template="day" let-day>
7        <div class="custom-day">
8          {{ day.getDate() }}
9          <!-- Add custom indicators or styling -->
10          <span *ngIf="isSpecialDay(day)" class="special-indicator">*</span>
11        </div>
12      </ng-template>
13
14      <!-- Custom month template -->
15      <ng-template dtp-template="month" let-month>
16        <div class="custom-month">
17          {{ getMonthName(month) }}
18          <!-- Add custom content -->
19        </div>
20      </ng-template>
21
22      <!-- Custom year template -->
23      <ng-template dtp-template="year" let-year>
24        <div class="custom-year">
25          {{ year }}
26          <!-- Add custom styling or indicators -->
27        </div>
28      </ng-template>
29    </persian-date-picker>
30  `
31})
32export class AppComponent {
33  isSpecialDay(date: Date): boolean {
34    // Your custom logic
35    return date.getDate() === 1;
36  }
37}

Read-only Mode

The DatePicker now supports two types of read-only modes:

1@Component({
2  template: `
3    <!-- Completely read-only - prevents both input and calendar interaction -->
4    <persian-date-picker
5      [(ngModel)]="selectedDate"
6      [readOnly]="true">
7    </persian-date-picker>
8
9    <!-- Read-only input but allows calendar interaction -->
10    <persian-date-picker
11      [(ngModel)]="selectedDate"
12      [readOnlyInput]="true">
13    </persian-date-picker>
14  `
15})

TimePicker Usage

The TimePicker is a separate component for time selection:

1
2@Component({
3  template: `
4    <persian-time-picker
5      [(ngModel)]="selectedTime"
6      [timeFormat]="'24'"
7      [showSeconds]="true"
8      [minTime]="'09:00'"
9      [maxTime]="'17:00'">
10    </persian-time-picker>
11  `
12})
13export class AppComponent {
14  selectedTime = '14:30:00';
15
16  // Or using Date object with valueType="date"
17  selectedDateTime = new Date();
18}

TimePicker with Custom Format

1
2<persian-time-picker
3  [(ngModel)]="time"
4  [timeFormat]="'12'"
5  [displayFormat]="'hh:mm a'"
6  [rtl]="true"
7  (timeChange)="onTimeChange($event)">
8</persian-time-picker>

Inline Mode with Date Adapter

1
2@Component({
3  template: `
4    <persian-time-picker
5      [(ngModel)]="time"
6      [inline]="true"
7      [dateAdapter]="gregorianDateAdapter"
8      [timeDisplayFormat]="'HH:mm:ss'"
9      (timeChange)="onTimeChange($event)">
10    </persian-time-picker>
11  `,
12})
13export class AppComponent {
14  constructor(public gregorianDateAdapter: GregorianDateAdapter) {
15  }
16}

Disabled Times

1
2@Component({
3  template: `
4    <persian-time-picker
5      [(ngModel)]="selectedTime"
6      [disabledTimesFilter]="disabledTimesFilter">
7    </persian-time-picker>
8  `
9})
10export class AppComponent {
11  // Disable lunch hours (12:00-13:00)
12  disabledTimesFilter = (date: Date) => {
13    const hour = date.getHours();
14    const minute = date.getMinutes();
15
16    // Disable specific hour
17    if (hour === 12) return true;
18
19    // Disable specific minutes
20    if (minute === 45) return true;
21
22    return false;
23  }
24}

API Reference

DatePicker Inputs

Input	Type	Default	Description
rtl	boolean	false	Right-to-left mode
mode	'day' | 'month' | 'year'	'day'	Selection mode
isRange	boolean	false	Enable range selection
format	string	'yyyy/MM/dd'	Date format
calendarType	'jalali' | 'gregorian'	'gregorian'	Calendar type
minDate	Date	null	Minimum selectable date
maxDate	Date	null	Maximum selectable date
cssClass	string	''	Custom CSS class
footerDescription	string	''	Footer description text
rangeInputLabels	RangeInputLabels	undefined	Labels for range inputs
inputLabel	string	undefined	Label for single input
placement	Placement	'bottomLeft'	Dropdown placement
disabled	boolean	false	Disable the datepicker
isInline	boolean	false	Show calendar inline
showSidebar	boolean	true	Show sidebar with months/years
showToday	boolean	false	Highlight today's date
valueFormat	'gregorian' | 'jalali' | 'date'	'gregorian'	Output value format
disableInputMask	boolean	false	To disable input mask
disabledDates	Array		string>
disabledDatesFilter	(date: Date) => boolean	undefined	Function to determine if a date should be disabled
disabledTimesFilter	(date: Date) => boolean	undefined	Function to determine if a time of date should be disabled
allowEmpty	boolean	true	Allow empty value
readOnly	boolean	false	Make the entire component read-only
readOnlyInput	boolean	false	Make only the input field read-only

DatePicker Outputs

Output	Type	Description
onFocus	EventEmitter	Fires when input receives focus
onBlur	EventEmitter	Fires when input loses focus
onChangeValue	EventEmitter	Fires when value changes
onOpenChange	EventEmitter	Fires when picker opens/closes

TimePicker Inputs

Input	Type	Default	Description
placeholder	string	'Select time'	Input placeholder
displayFormat	string	'hh:mm a'	Time display format
minTime	string	undefined	Minimum selectable time
maxTime	string	undefined	Maximum selectable time
valueType	'string' | 'date'	'string'	Output value type
cssClass	string	''	Custom CSS class
showIcon	boolean	true	Show clock icon
rtl	boolean	false	Right-to-left mode
lang	LanguageLocale	EnglishLocale	Language settings
inline	boolean	false	Show time picker inline (without popup)
dateAdapter	DateAdapter	undefined	Custom date adapter for time manipulation
disableInputMask	boolean	false	To disable input mask
disabledTimesFilter	(date: Date) => boolean	undefined	Function to determine if a time should be disabled
disabled	boolean	false	Disable the time picker
allowEmpty	boolean	true	Allow empty value
readOnly	boolean	false	Make the entire component read-only
readOnlyInput	boolean	false	Make only the input field read-only

TimePicker Outputs

Output	Type	Description
timeChange	EventEmitter	Fires when time changes
openChange	EventEmitter	Fires when picker opens/closes

Form Integration Examples

Reactive Forms with Both Components

1
2@Component({
3  template: `
4    <form [formGroup]="form">
5      <!-- Date Range -->
6      <persian-date-picker
7        formControlName="dateRange"
8        [isRange]="true"
9        [calendarType]="'jalali'">
10      </persian-date-picker>
11
12      <!-- Time -->
13      <persian-time-picker
14        formControlName="time"
15        [timeFormat]="'24'">
16      </persian-time-picker>
17    </form>
18  `
19})
20export class AppComponent {
21  form = this.formBuilder.group({
22    dateRange: [{
23      start: '1403/08/12',
24      end: new Date()
25    }],
26    time: ['14:30']
27  });
28
29  constructor(private formBuilder: FormBuilder) {
30  }
31}

Inline Mode

1
2<persian-time-picker
3  [(ngModel)]="time"
4  [inline]="true"
5  [timeFormat]="'24'"
6  [displayFormat]="'HH:mm:ss'">
7</persian-time-picker>

Calendar Types and Localization

The TimePicker automatically adapts to your chosen calendar system:

1<!-- Jalali (Persian) Time Picker-->
2<persian-time-picker
3  [(ngModel)]="time"
4  [rtl]="true"
5  [timeFormat]="'12'">
6</persian-time-picker>
7
8<!-- Gregorian Time Picker-->
9<persian-time-picker
10  [(ngModel)]="time"
11  [rtl]="false"
12  [timeFormat]="'24'">
13</persian-time-picker>

Template-driven Forms

1
2<form>
3  <persian-date-picker
4    [(ngModel)]="dateRange"
5    name="dateRange"
6    [isRange]="true"
7    required>
8  </persian-date-picker>
9
10  <persian-time-picker
11    [(ngModel)]="time"
12    name="time"
13    required>
14  </persian-time-picker>
15</form>

Styling

Both components can be styled using CSS variables:

1.persian-time-picker {
2  --primary-color: #40a9ff;
3  --border-color: #d9d9d9;
4  --text-color: #666;
5  --background-color: white;
6  --hover-background: #f5f5f5;
7  --selected-background: #e6f4ff;
8  --selected-text-color: #1890ff;
9  --disabled-color: #d9d9d9;
10}
11
12/* Inline mode specific styles */
13.time-picker-popup.inline {
14  border: 1px solid var(--border-color);
15  border-radius: 8px;
16}

Contributing

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

License

MIT License