Date Picker

This is a configurable date-picker build for Angular applications.
Supports latest (Angular 15) version. For older versions please checkout the CHANGELOG.md file.

DEMO

Screenshots

Day:

DayTime:

Month:

Time:

Installation:

1. Download from npm:
   npm install ng2-date-picker --save
2. Import the DpDatePickerModule module:
   import {DpDatePickerModule} from 'ng2-date-picker';
3. Add DpDatePickerModule to your module imports:

1 @NgModule({ ... imports: [ ... DpDatePickerModule ] })

4. Add @import '~@angular/cdk/overlay-prebuilt.css'; to your global styles (usually styles.(scss/sass/css/less). You could also add it via the angular.json file under the styles attribute:

 "projects": {
    "your-project": {
      ...
      "architect": {
        "build": {
          ...
          "options": {
            ...
            "styles": [
              ...
              "node_modules/@angular/cdk/overlay-prebuilt.css"
            ],
   ...    

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

Usage

Put the dp-date-picker component wherever you need it.

Locale

In order to change the locale you will need first to import the locale you want to work with and apply it to the Dayjs object. More information about this can be found in the dayjs documentation here.
Note: The locale is set to en by default. If you change the locale after the first initialization of the date-picker then you will need to reinitialize the date-picker.

Attributes (Input):

Name	Type	Default	Applies To	Description
mode	"day"|"month"|"time"|"daytime"	"day"	All	The mode of the calender which will be displayed in the picker
displayDate	Dayjs|String	current date	day|month|daytime	Indicates on what date to open the calendar on
disabled	Boolean	false	All	If set to true the input would be disabled
placeholder	String	""	All	The date-picker input placeholder
required	Boolean	undefined	All	This is a validation rule, if there won't be any selected date then the containing form will be invalid.
minDate	Dayjs|String	undefined	day|month|daytime	This is a validation rule, if the selected date will be before minDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
maxDate	Dayjs|String	undefined	day|month|daytime	This is a validation rule, if the selected date will be after maxDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
minTime	Dayjs|String	undefined	time	This is a validation rule, if the selected date will be before minTime the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
maxTime	Dayjs|String	undefined	time	This is a validation rule, if the selected date will be after maxTime the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
theme	String	""	All	Theme is a class added to the popup container (and inner components) - this will allow styling of the calendar when it's appended to outer element (for example - body). There is a built in theme named dp-material, you can find it in the demo.
config	IDatePickerConfig	See Below	All	Configuration object - see description below.

Attributes (Output):

Name	Event Arguments	Applies To	Description
onChange	CalendarValue	All Pickers	This event will be emitted on every valid value change, if you want to receive every value (valid and invalid) please use the native ngModelChange output.
open	undefined	All Pickers	This event will be emitted when picker is opened.
close	CalendarValue	All Pickers	This event will be emitted when picker is closed.
onGoToCurrent	void	All Pickers	This event will be emitted when click was made on go to current button.
onLeftNav	void	All Pickers	This event will be emitted when click was made on left navigation button.
onRightNav	void	All Pickers	This event will be emitted when click was made on right navigation button.
onSelect	ISelectionEvent	All Pickers	This event will be emitted when a date was selected via click or input change (with appropriate indication)

Configuration: In order to provide configurations to the date-picker you need to pass it to the dp-date-picker component:

1<dp-date-picker [(ngModel)]="selectedDate" [config]="datePickerConfig"></dp-date-picker>  

Here are the available configurations:

Name	Type	Default	Applies To	Description
disableKeypress	Boolean	false	All	Disables the possibility to change the date value by typing it - changing the date would be possible only from the picker
format	String	"DD-MM-YYYY"	All	If ngModel provided as String the format is required, this format also will be used as the input format style.
onOpenDelay	Number	0	All	The delay (in ms) between the date picker focusing and the date-picker popup apparel
drops	'up'| 'down'	undefined down if possible	All	Whether the picker appears below or above the input element.
opens	'right'| 'left'	undefined right if possible	All	Whether the picker appears aligned to the left or to the right the input element.
closeOnSelect	Boolean	true	`day\	month`
openOnClick	Boolean	true	`day\	month|daytime`
openOnFocus	Boolean	true	`day\	month|daytime`
closeOnSelectDelay	Number	100	`day\	month`
allowMultiSelect	Boolean	undefined	`day\	month`
dayBtnFormat	String	DD	`day\	daytime`
dayBtnFormatter	(Dayjs) => String	undefined	`day\	daytime`
dayBtnCssClassCallback	(Dayjs) => String	undefined	`day\	daytime`
enableMonthSelector	Boolean	true	`day\	daytime`
firstDayOfWeek	String	"su"	`day\	daytime`
isDayDisabledCallback	(Dayjs) => boolean	undefined	`day\	daytime`
monthFormat	String	"MMM-YYYY"	`day\	daytime`
monthFormatter	(Dayjs) => String	undefined	`day\	daytime`
showNearMonthDays	Boolean	true	`day\	daytime`
showWeekNumbers	Boolean	false	`day\	daytime`
isMonthDisabledCallback	(Dayjs) => boolean	undefined	`day\	month|daytime`
max	Dayjs| String	undefined	day|month|daytime	Disables all dates (on the date-picker) that are set to after the max, note that if invalid date would be set by the input then the date picker value would be the max date but the input will show the user typed date.
min	Dayjs| String	undefined	day|month|daytime	Disables all dates (on the date-picker) that are set to before the min, note that if invalid date would be set by the input then the date picker value would be the min date but the input will show the user typed date.
monthBtnFormat	String	DD	`day\	month|daytime`
monthBtnFormatter	(Dayjs) => String	undefined	`day\	month|daytime`
monthBtnCssClassCallback	(Dayjs) => String	undefined	`day\	month|daytime`
yearFormat	String	"YYYY"	`day\	month|daytime`
yearFormatter	(Dayjs) => String	undefined	`day\	month|daytime`
hours12Format	String	"hh"	`daytime\	time`
hours24Format	String	"HH"	`daytime\	time`
maxTime	Dayjs| String	undefined	daytime|time	Disables arrow buttons on the time select that would make the time after the maxTime.
meridiemFormat	String	"A"	`daytime\	time`
minTime	Dayjs| String	undefined	daytime|time	Disables arrow buttons on the time select that would make the time before the minTime.
minutesFormat	String	"mm"	`daytime\	time`
minutesInterval	number	1	`daytime\	time`
secondsFormat	String	"ss"	`daytime\	time`
secondsInterval	number	1	`daytime\	time`
showSeconds	boolean	false	`daytime\	time`
showTwentyFourHours	boolean	false	`daytime\	time`
timeSeparator	String	":"	`daytime\	time`
showMultipleYearsNavigation	boolean	false	`day\	month|daytime`
multipleYearsNavigateBy	number	10	`day\	month|daytime`
returnedValueType	ECalendarValue	Dayjs	All	The returned value type (Dayjs, Dayjs[], string, string[]
unSelectOnClick	boolean	true	`day\	month`
inputElementContainer	string| HTMLElement| ElementRef	undefined	All	Will place picker popup relative to the provided elemenr (if string provided will used as a selector)
showGoToCurrent	boolean	true	All	Show/Hides the go to current button on the calendars navigation
hideOnOutsideClick	boolean	true	All	Show/Hides the picker popup after click outside of the component
closeOnEnter	boolean	true	All	Hides the picker popup after enter button keypress

API:

In order to use the date-picker api user the @ViewChild annotation in the date-picker containing component class, take at the example below:
Container component:

1import {DatePickerComponent} from 'ng2-date-picker';  
2  
3@Component({  
4selector: 'my-container',  
5template: `  
6<div>  
7 <h1>Container</h1> <dp-date-picker #dayPicker></dp-date-picker> <button (click)="open()"></button> <button (click)="close()"></button></div>  
8`  
9});  
10class MyContainer {  
11 @ViewChild('dayPicker') datePicker: DatePickerComponent;  
12 open() { this.datePicker.api.open(); }  
13 close() { this.datePicker.api.close(); }} ```  
14  
15If you want to use API with [`Directive`](#directive) - you can do it by using `#dateDirectivePicker`, like below:  
16```ts  
17import {Component, ViewChild} from '@angular/core';  
18import {DatePickerDirective} from 'ng2-date-picker';  
19  
20@Component({  
21selector: 'my-container',  
22template: `  
23<div>  
24 <input #dateDirectivePicker="dpDayPicker"> <button (click)="close()"></button></div>  
25`  
26});  
27class MyContainer {  
28 @ViewChild('dateDirectivePicker') datePickerDirective: DatePickerDirective;     close() {  
29 this.datePickerDirective.api.close(); }} ```  
30  
31Here is the list of APIs:    
32  
33| Name                 | Signature                          | Description                      |  
34|----------------------|:----------------------------------:|----------------------------------|  
35| open                 | `() => void`                       | Opens the date picker            |  
36| close                | `() => void`                       | Closes the date picker           |  
37| moveCalendarTo       | `(to: Dayjs \| String) => void`   | Moves calendar to specific date  |  
38  
39## Inline - Day Calendar  
40  
41You can use the `<dp-day-calendar>` component to display the calendar widget without an associated input box.  
42  
43i.e.  
44```html  
45<dp-day-calendar [(ngModel)]="selectedDate" [config]="config"></dp-day-calendar>  

Attributes:

Name	Type	Default	Description
required	Boolean	undefined	This is a validation rule, if there won't be any selected date then the containing form will be invalid.
minDate	Dayjs|String	undefined	This is a validation rule, if the selected date will be before minDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
maxDate	Dayjs|String	undefined	This is a validation rule, if the selected date will be after maxDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
theme	String	''	Theme is a class added to the popup container (and inner components) - this will allow styling of the calendar when it's appended to outer element (for example - body). There is a built in theme named dp-material, you can find it in the demo.
config	IDayCalendarConfig	See Below	Configuration object - see description below.

Attributes (Output):

Name	Event Arguments	Description
onSelect	IDay	This event will be emitted when a day is selected.
onMonthSelect	IMonth	This event will be emitted when a month is selected.
onNavHeaderBtnClick	ECalendarMode	This event will be emitted when the mode of the calendar switches form day to month and vise versa.
onGoToCurrent	void	This event will be emitted when click was made on go to current button.
onLeftNav	void	This event will be emitted when click was made on left navigation button.
onRightNav	void	This event will be emitted when click was made on right navigation button.

Configuration: In order to provide configurations to the day-calendar you need to pass it to the dp-day-calendar component:

1<dp-day-calendar [(ngModel)]="selectedDate" [config]="config"></dp-day-calendar>  

Here are the available configurations:

Name	Type	Default	Description
format	String	"DD-MM-YYYY"	If ngModel provided as String the format is required, this format also will be used as the input format style.
firstDayOfWeek	String	"su"	The first day of the calendar's week. Should be one of: "su", "mo", "tu", "we", "th", "fr", "sa"
monthFormat	String	"MMM-YYYY"	The date format of the day calendar, the one that seen above the calendar days. Will be overwritten if monthFormatter provided.
monthFormatter	(Dayjs) => String	undefined	The date formatter (callback function) of the day calendar, the one that seen above the calendar days.
yearFormat	String	"YYYY"	The date format of the month calendar, the one that seen above the calendar months. Will be overwritten if yearFormatter provided. (available when enableMonthSelector is set to true).
yearFormatter	(Dayjs) => String	undefined	The date formatter (callback function) of the month calendar, the one that seen above the calendar months. (available when enableMonthSelector is set to true).
allowMultiSelect	Boolean	undefined	If set to true will allow for choosing multiple dates. false will force a single selection. If undefined, the picker will attempt to guess based on the type of the input value.
min	Dayjs|String	undefined	Disables all dates (on the date-picker) that are set to before the min, note that if invalid date would be set by the input then the date picker value would be the min date but the input will show the user typed date.
max	Dayjs|String	undefined	Disables all dates (on the date-picker) that are set to after the max, note that if invalid date would be set by the input then the date picker value would be the max date but the input will show the user typed date.
showNearMonthDays	Boolean	true	Whether to show/hide next and previous month days.
showWeekNumbers	Boolean	false	Whether to show/hide the week number of each week (iso week number).
enableMonthSelector	Boolean	true	Whether to enable/disable the selection of a moth granularity picker.
isDayDisabledCallback	(Dayjs) => boolean	undefined	Callback which should indicate if specific day is disabled.
isMonthDisabledCallback	(Dayjs) => boolean	undefined	Callback which should indicate if specific month is disabled (month selector).
dayBtnFormat	String	DD	The day format of the day button in the calendar.
dayBtnFormatter	(Dayjs) => String	undefined	The formatter (callback function) of the day button in the calendar.
dayBtnCssClassCallback	(Dayjs) => String	undefined	Callback which can add custom CSS classes to the day button in the calendar. Multiple classes can be returned with a space between them.
monthBtnFormat	String	DD	The month format of the month button in the calendar.
monthBtnFormatter	(Dayjs) => String	undefined	The formatter (callback function) of the month button in the calendar.
monthBtnCssClassCallback	(Dayjs) => String	undefined	Callback which can add custom CSS classes to the month button in the calendar. Multiple classes can be returned with a space between them.
showMultipleYearsNavigation	boolean	false	If set to true will show buttons to navigate by multiple years (10 by default)
multipleYearsNavigateBy	number	10	Number of years to navigate when showMultipleYearsNavigation is true
numOfMonthRows	1, 2, 3, 4, 6, 12	4	Number of rows to be shown on month calendar

Inline - Month Calendar

You can use the <dp-month-calendar> component to display the calendar widget without an associated input box.
i.e.

1<dp-month-calendar [(ngModel)]="selectedDate" [config]="config"></dp-month-calendar>  

Attributes:

Name	Type	Default	Description
required	Boolean	undefined	This is a validation rule, if there won't be any selected date then the containing form will be invalid.
minDate	Dayjs|String	undefined	This is a validation rule, if the selected date will be before minDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
maxDate	Dayjs|String	undefined	This is a validation rule, if the selected date will be after maxDate the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
theme	String	''	Theme is a class added to the popup container (and inner components) - this will allow styling of the calendar when it's appended to outer element (for example - body). There is a built in theme named dp-material, you can find it in the demo.
config	IMonthPickerConfig	See Below	Configuration object - see description below.

Attributes (Output):

Name	Event Arguments	Description
onSelect	IMonth	This event will be emitted when a month is selected.
onNavHeaderBtnClick	null	This event will be emitted when the mode button, in the navigation section, was clicked.
onGoToCurrent	void	This event will be emitted when click was made on go to current button.
onLeftNav	void	This event will be emitted when click was made on left navigation button.
onRightNav	void	This event will be emitted when click was made on right navigation button.

Configuration: In order to provide configurations to the month-calendar you need to pass it to the dp-month-calendar component:

1<dp-month-calendar [(ngModel)]="selectedDate" [config]="config"></dp-month-calendar>  

Here are the available configurations:

Name	Type	Default	Description
format	String	"DD-MM-YYYY"	If ngModel provided as String the format is required, this format also will be used as the input format style.
yearFormat	String	"YYYY"	The date format of the month calendar, the one that seen above the calendar months. Will be overwritten if yearFormatter provided. (available when enableMonthSelector is set to true).
yearFormatter	(Dayjs) => String	undefined	The date formatter (callback function) of the month calendar, the one that seen above the calendar months. (available when enableMonthSelector is set to true).
allowMultiSelect	Boolean	undefined	If set to true will allow for choosing multiple dates. false will force a single selection. If undefined, the picker will attempt to guess based on the type of the input value.
min	Dayjs|String	undefined	Disables all dates (on the date-picker) that are set to before the min, note that if invalid date would be set by the input then the date picker value would be the min date but the input will show the user typed date.
max	Dayjs|String	undefined	Disables all dates (on the date-picker) that are set to after the max, note that if invalid date would be set by the input then the date picker value would be the max date but the input will show the user typed date.
isMonthDisabledCallback	(Dayjs) => boolean	undefined	Callback which should indicate if specific month is disabled (month selector).
monthBtnFormat	String	DD	The month format of the month button in the calendar.
monthBtnFormatter	(Dayjs) => String	undefined	The formatter (callback function) of the month button in the calendar.
monthBtnCssClassCallback	(Dayjs) => String	undefined	Callback which can add custom CSS classes to the month button in the calendar. Multiple classes can be returned with a space between them.
showMultipleYearsNavigation	boolean	false	If set to true will show buttons to navigate by multiple years (10 by default)
multipleYearsNavigateBy	number	10	Number of years to navigate when showMultipleYearsNavigation is true
numOfMonthRows	1, 2, 3, 4, 6, 12	4	Number of rows to be shown on month calendar

Here is the list of APIs:

Name	Signature	Description
moveCalendarsBy	(current: Dayjs, amount: number, granularity: dayjs.TimeUnit) => void	Moves calendar by given amount
moveCalendarTo	`(to: Dayjs \	String) => void`
toggleCalendarMode	`(mode: day \	month) => void`

Inline - Time Select

You can use the <dp-time-select> component to display the time select widget without an associated input box.

i.e.

1<dp-time-select [(ngModel)]="selectedDate" [config]="config"></dp-time-select>  

Attributes:

Name	Type	Default	Description
required	Boolean	undefined	This is a validation rule, if there won't be any selected date then the containing form will be invalid.
minTime	Dayjs|String	undefined	This is a validation rule, if the selected date will be before minTime the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
maxTime	Dayjs|String	undefined	This is a validation rule, if the selected date will be after maxTime the containing form will be invalid. Note: if provided as string format configuration should be provided in the config object.
theme	String	''	Theme is a class added to the popup container (and inner components) - this will allow styling of the calendar when it's appended to outer element (for example - body). There is a built in theme named dp-material, you can find it in the demo.
config	ITimeSelectConfig	See Below	Configuration object - see description below.

Attributes (Output):

Name	Event Arguments	Description
onChange	IDate	This event will be emitted when time is selected.

Configuration: In order to provide configurations to the time-select you need to pass it to the dp-time-select component:

1<dp-time-select [(ngModel)]="selectedDate" [config]="config"></dp-time-select>  

Here are the available configurations:

Name	Type	Default	Description
hours12Format	String	"hh"	The hours format of the time select when showTwentyFourHours is false.
hours24Format	String	"HH"	The hours format of the time select when showTwentyFourHours is true.
maxTime	Dayjs|String	undefined	Disables arrow buttons on the time select that would make the time after the maxTime.
meridiemFormat	String	"A"	The AM/PM format of the time select when showTwentyFourHours is false.
minTime	Dayjs|String	undefined	Disables arrow buttons on the time select that would make the time before the minTime.
minutesFormat	String	"mm"	The minutes format of the time select.
minutesInterval	number	1	The number of minutes that will be added/subtracted when clicking up/down arrows on the time select.
secondsFormat	String	"ss"	The seconds format of the time select.
secondsInterv