ngx-angular-datepicker

A modern Persian Jalali (Shamsi) Datepicker component for Angular applications.

ngx-angular-datepicker is a lightweight Angular date picker designed for Persian applications with full Jalali calendar support, RTL layout, Persian numbers, custom date formats, optional time picker, date restrictions, and Angular Forms support.

Features

✨ Features included:

• 🇮🇷 Jalali (Shamsi) calendar support
• 🔢 Persian number formatting
• ↔️ RTL support
• 📅 Month and year selection
• ⏰ Optional time picker
• 🎨 Custom date format support
• 🗓 Correct Jalali leap year handling
• ⚡ Angular Standalone Component support
• 📦 NgModule support
• 📝 Reactive Forms support
• 🔗 ControlValueAccessor support
• 🚫 Min / Max date limitation
• 🚫 Disable specific dates
• 🎯 Modern and lightweight UI

Installation

Install the package using npm:

npm install ngx-angular-datepicker

Usage

Standalone Component

For Angular standalone applications:

import { Component } from '@angular/core';
import { NgxDatePickerComponent, JalaliDate } from 'ngx-angular-datepicker';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgxDatePickerComponent],
  template: `
    <ngx-date-picker [value]="selectedDate" (dateChange)="onDateChange($event)"> </ngx-date-picker>
  `,
})
export class AppComponent {
  selectedDate: JalaliDate = {
    year: 1405,
    month: 4,
    day: 20,
  };

  onDateChange(date: JalaliDate): void {
    console.log('Selected date:', date);
  }
}

NgModule Support

The package also supports traditional Angular module based applications.

Import the module:

import { NgxAngularDatepickerModule } from 'ngx-angular-datepicker';

@NgModule({
  imports: [NgxAngularDatepickerModule],
})
export class AppModule {}

Then use:

<ngx-date-picker> </ngx-date-picker>

Basic Example

<ngx-date-picker> </ngx-date-picker>

If no value is provided, the component automatically uses today's Jalali date.

Set Default Date

You can provide an initial selected date:

<ngx-date-picker
  [value]="{
  year: 1405,
  month: 4,
  day: 20
}"
>
</ngx-date-picker>

Output:

{
  year: 1405,
  month: 4,
  day: 20
}

Reactive Forms Support

The date picker supports Angular Reactive Forms using ControlValueAccessor.

Example:

import { FormControl } from '@angular/forms';
import { JalaliDate } from 'ngx-angular-datepicker';

birthDate = new FormControl<JalaliDate | null>({
  year: 1405,
  month: 4,
  day: 20,
  hour: 14,
  minute: 30,
});

HTML:

<ngx-date-picker [formControl]="birthDate"> </ngx-date-picker>

Selected value:

{
  year: 1405,
  month: 4,
  day: 20,
  hour: 14,
  minute: 30
}

Enable Time Picker

Enable hour and minute selection:

<ngx-date-picker [enableTime]="true"> </ngx-date-picker>

Output:

{
  year: 1405,
  month: 4,
  day: 20,
  hour: 14,
  minute: 30
}

Custom Date Format

You can customize the displayed date format:

<ngx-date-picker format="DD MMMM YYYY"> </ngx-date-picker>

Examples:

| Format | Output | | -------------- | ------------- | | YYYY/MM/DD | ۱۴۰۵/۰۵/۲۰ | | DD-MM-YYYY | ۲۰-۰۵-۱۴۰۵ | | DD MMMM YYYY | ۲۰ مرداد ۱۴۰۵ | | MMMM YYYY | مرداد ۱۴۰۵ |

Available tokens:

| Token | Description | | ----- | ------------------ | | YYYY | Jalali year | | MM | Numeric month | | DD | Numeric day | | MMMM | Persian month name |

Min Date / Max Date

Limit selectable dates:

<ngx-date-picker
  [minDate]="{
  year:1405,
  month:1,
  day:1
}"
  [maxDate]="{
  year:1405,
  month:6,
  day:1
}"
>
</ngx-date-picker>

Disable Specific Dates

Disable selected dates:

<ngx-date-picker
  [disabledDates]="[

 {
   year:1405,
   month:4,
   day:10
 },

 {
   year:1405,
   month:4,
   day:11
 }

]"
>
</ngx-date-picker>

Disable Component

<ngx-date-picker [disabled]="true"> </ngx-date-picker>

Placeholder

Custom input placeholder:

<ngx-date-picker placeholder="تاریخ تولد"> </ngx-date-picker>

Complete Example

<ngx-date-picker
  placeholder="تاریخ تولد"
  [value]="selectedDate"
  [minDate]="{
  year:1405,
  month:1,
  day:1
}"
  [maxDate]="{
  year:1405,
  month:12,
  day:29
}"
  [disabledDates]="disabledDates"
  [enableTime]="true"
  format="DD MMMM YYYY"
  (dateChange)="onDateChange($event)"
>
</ngx-date-picker>

JalaliDate Interface

export interface JalaliDate {
  year: number;

  month: number;

  day: number;

  hour?: number;

  minute?: number;
}

Configuration Options

| Option | Type | Default | Description | | ------------- | ------------ | ------------ | ----------------------- | | value | JalaliDate | undefined | Initial selected date | | placeholder | string | انتخاب تاریخ | Input placeholder | | enableTime | boolean | false | Enable time picker | | format | string | YYYY/MM/DD | Display format | | minDate | JalaliDate | undefined | Minimum selectable date | | maxDate | JalaliDate | undefined | Maximum selectable date | | disabledDates | JalaliDate[] | [] | Disabled dates | | disabled | boolean | false | Disable component |

Angular Compatibility

| Angular Version | Support | | --------------- | ------- | | Angular 20 | ✅ | | Angular 19 | ✅ | | Angular 18 | ✅ | | Angular 17 | ✅ | | Angular 16 | ✅ | | Angular 15 | ✅ |

Contributing

Contributions are welcome ❤️

If you find a bug, have an idea, or want to improve this project:

• Open an issue
• Submit a pull request
• Share your feedback

I would be happy to see developers from the Angular community contribute and help make this package better.

Author

Created by Araz Shamsaddinlouy

Senior Front-End Engineer focused on:

• Angular
• React
• Next.js
• TypeScript

Connect with me

LinkedIn:

https://linkedin.com/in/araz-shams

Portfolio:

https://arazshams.vercel.app

GitHub:

https://github.com/arazshamsaddinlouy

License

MIT License