Calendar

Calendar is an input component to select a date.

Import #


import { CalendarModule } from 'primeng/calendar';

Basic #

Two-way value binding is defined using the standard ngModel directive referencing to a Date property.


<p-calendar [(ngModel)]="date"></p-calendar>

Reactive Forms #

Calendar can also be used with reactive forms. In this case, the formControlName property is used to bind the component to a form control.


<form [formGroup]="formGroup">
    <p-calendar formControlName="date"></p-calendar>
</form>

Format #

Default date format is mm/dd/yy which can be customized using the dateFormat property. Following options can be a part of the format.

d - day of month (no leading zero)
dd - day of month (two digit)
o - day of the year (no leading zeros)
oo - day of the year (three digit)
D - day name short
DD - day name long
m - month of year (no leading zero)
mm - month of year (two digit)
M - month name short
MM - month name long
y - year (two digit)
yy - year (four digit)
@ - Unix timestamp (ms since 01/01/1970)
! - Windows ticks (100ns since 01/01/0001)
'...' - literal text
'' - single quote
anything else - literal text


<p-calendar [(ngModel)]="date" dateFormat="dd.mm.yy"></p-calendar>

Locale #

Locale for different languages and formats is defined globally, refer to the PrimeNG Locale configuration for more information.

Icon #

An additional icon is displayed next to the input field when showIcon is present.


<p-calendar [(ngModel)]="date" [showIcon]="true"></p-calendar>

Min / Max #

Boundaries for the permitted dates that can be entered are defined with minDate and maxDate properties.


<p-calendar [(ngModel)]="date" [minDate]="minDate" [maxDate]="maxDate" [readonlyInput]="true"></p-calendar>

Multiple #

In order to choose multiple dates, set selectionMode as multiple. In this mode, the value binding should be an array.


<p-calendar [(ngModel)]="dates" selectionMode="multiple" [readonlyInput]="true"></p-calendar>

Range #

A range of dates can be selected by defining selectionMode as range, in this case the bound value would be an array with two values where first date is the start of the range and second date is the end.


<p-calendar [(ngModel)]="rangeDates" selectionMode="range" [readonlyInput]="true"></p-calendar>

ButtonBar #

When showButtonBar is present, today and clear buttons are displayed at the footer.


<p-calendar [(ngModel)]="date" [showButtonBar]="true"></p-calendar>

Time #

TimePicker is enabled with showTime property and 24 (default) or 12 hour mode is configured using hourFormat option.


<p-calendar [(ngModel)]="date" [showTime]="true" [showSeconds]="true"></p-calendar>

Month Picker #

Month only picker is enabled by specifying view as month in addition to a suitable dateFormat.


<p-calendar [(ngModel)]="date" view="month" dateFormat="mm/yy" [readonlyInput]="true"></p-calendar>

Year Picker #

Similar to the month picker, year picker can be used to select years only. Set view to year to display the year picker.


<p-calendar [(ngModel)]="date" view="year" dateFormat="yy" inputId="yearpicker"></p-calendar>

Multiple Months #

Number of months to display is configured with the numberOfMonths property.


<p-calendar [(ngModel)]="date" [numberOfMonths]="3"></p-calendar>

Custom Content #

Calendar UI accepts custom content using header and footer templates.


<p-calendar [(ngModel)]="date">
    <ng-template pTemplate="header">Header</ng-template>
    <ng-template pTemplate="footer">Footer</ng-template>
</p-calendar>

Date Template #

Custom content can be placed inside date cells with the ng-template property that takes a Date as a parameter.


<p-calendar [(ngModel)]="date">
    <ng-template pTemplate="date" let-date>
        <span [ngStyle]="{textDecoration: (date.day < 21 && date.day > 10) ? 'line-through' : 'inherit'}">{{date.day}}</span>
    </ng-template>
</p-calendar>

TouchUI #

When touchUI is enabled, overlay is displayed as optimized for touch devices.


<p-calendar [(ngModel)]="date" [touchUI]="true" [readonlyInput]="true"></p-calendar>

Inline #

Calendar is displayed as a popup by default, add inline property to customize this behavior.

Wk	Su	Mo	Tu	We	Th	Fr	Sa
47	26	27	28	29	30	1	2
48	3	4	5	6	7	8	9
49	10	11	12	13	14	15	16
50	17	18	19	20	21	22	23
51	24	25	26	27	28	29	30
52	31	1	2	3	4	5	6


<p-calendar class="max-w-full" [(ngModel)]="date" [inline]="true" [showWeek]="true"></p-calendar>

Style #

Following is the list of structural style classes, for theming classes visit theming page.

Name	Element
p-calendar	Main container element
p-calendar-w-btn	Main container element when button is enabled.
p-calendar-timeonly	Main container element in time picker only mode.
p-inputtext	Input element
p-datepicker	Datepicker element
p-datepicker-inline	Datepicker element in inline mode
p-datepicker-monthpicker	Datepicker element in month view.
p-datepicker-touch-p	Datepicker element in touch p mode.
p-datepicker-calendar	Table containing dates of a month.
p-datepicker-current-day	Cell of selected date.
p-datepicker-today	Cell of today's date.

Accessibility #

Screen Reader

Value to describe the component can either be provided via label tag combined with inputId prop or using aria-labelledby, aria-label props. The input element has combobox role in addition to aria-autocomplete as "none", aria-haspopup as "dialog" and aria-expanded attributes. The relation between the input and the popup is created with aria-controls attribute that refers to the id of the popup.

The optional calendar button requires includes aria-haspopup, aria-expanded for states along with aria-controls to define the relation between the popup and the button. The value to read is retrieved from the chooseDate key of the aria property from the locale API. This label is also used for the aria-label of the popup as well. When there is a value selected, it is formatted and appended to the label to be able to notify users about the current value.

Popup has a dialog role along with aria-modal and aria-label. The navigation buttons at the header has an aria-label retrieved from the prevYear, nextYear, prevMonth, nextMonth,prevDecade and nextDecade keys of the locale aria API. Similarly month picker button uses the chooseMonth and year picker button uses the chooseYear keys.

Main date table uses grid role that contains th elements with col as the scope along with abbr tag resolving to the full name of the month. Each date cell has an aria-label referring to the full date value. Buttons at the footer utilize their readable labels as aria-label as well. Selected date also receives the aria-selected attribute.

Timepicker spinner buttons get their labels for aria-label from the aria locale API using the prevHour, nextHour, prevMinute, nextMinute, prevSecond, nextSecond, am and pm keys.

Calendar also includes a hidden section that is only available to screen readers with aria-live as "polite". This element is updated when the selected date changes to instruct the user about the current date selected.


<label for="date1">Date</label>
<p-calendar inputId="date1"></p-calendar>

<span id="date2">Date</span>
<p-calendar ariaLabelledBy="date2"></p-calendar>

<p-calendar ariaLabel="Date"></p-calendar>

Choose Date Button Keyboard Support

Key	Function
space	Opens popup and moves focus to the selected date, if there is none focuses on today.
enter	Opens popup and moves focus to the selected date, if there is none focuses on today.

Popup Keyboard Support

Key	Function
escape	Closes the popup and moves focus to the input element.
tab	Moves focus to the next focusable element within the popup.
shift + tab	Moves focus to the next focusable element within the popup.

Header Buttons Keyboard Support

Key	Function
enter	Triggers the button action.
space	Triggers the button action.

Date Grid Keyboard Support

Key	Function
enter	Selects the date, closes the popup and moves focus to the input element.
space	Selects the date, closes the popup and moves focus to the input element.
up arrow	Moves focus to the same day of the previous week.
down arrow	Moves focus to the same day of the next week.
right arrow	Moves focus to the next day.
left arrow	Moves focus to the previous day.
home	Moves focus to the first day of the current week.
end	Moves focus to the last day of the current week.
page up	Changes the date to previous month in date picker mode. Moves to previous year in month picker mode and previous decade in year picker.
shift + page up	Changes the date to previous year in date picker mode. Has no effect in month or year picker
page down	Changes the date to next month in date picker mode. Moves to next year in month picker mode and next decade in year picker.
shift + page down	Changes the date to next year in date picker mode. Has no effect in month or year picker

Footer Buttons Keyboard Support

Key	Function
enter	Triggers the button action.
space	Triggers the button action.

Calendar API

API defines helper props, events and others for the PrimeNG Calendar module.

Calendar #

Calendar also known as DatePicker, is a form component to work with dates.

Properties #

Defines the input properties of the component.

name	type	default	description
style	Object	null	Inline style of the component.
styleClass	string	null	Style class of the component.
inputStyle	Object	null	Inline style of the input field.
inputId	string	null	Identifier of the focus input to match a label defined for the component.
name	string	null	Name of the input element.
inputStyleClass	string	null	Style class of the input field.
placeholder	string	null	Placeholder text for the input.
ariaLabelledBy	string	null	Establishes relationships between the component and label(s) where its value should be one or more element IDs.
ariaLabel	string	null	Defines a string that labels the input for accessibility.
iconAriaLabel	string	null	Defines a string that labels the icon button for accessibility.
disabled	boolean	false	When specified, disables the component.
dateFormat	string	null	Format of the date which can also be defined at locale settings.
multipleSeparator	string	,	Separator for multiple selection mode.
rangeSeparator	string	-	Separator for joining start and end dates on range selection mode.
inline	boolean	false	When enabled, displays the calendar as inline. Default is false for popup mode.
showOtherMonths	boolean	true	Whether to display dates in other months (non-selectable) at the start or end of the current month. To make these days selectable use the selectOtherMonths option.
selectOtherMonths	boolean	false	Whether days in other months shown before or after the current month are selectable. This only applies if the showOtherMonths option is set to true.
showIcon	boolean	false	When enabled, displays a button with icon next to input.
icon	string	null	Icon of the calendar button.
appendTo	any	null	Target element to attach the overlay, valid values are "body" or a local ng-template variable of another element (note: use binding with brackets for template variables, e.g. [appendTo]="mydiv" for a div element having#mydiv as variable name).
readonlyInput	boolean	false	When specified, prevents entering the date manually with keyboard.
shortYearCutoff	any	+10	The cutoff year for determining the century for a date.
monthNavigator	boolean	false	Whether the month should be rendered as a dropdown instead of text.
yearNavigator	boolean	false	Whether the year should be rendered as a dropdown instead of text.
hourFormat	string	24	Specifies 12 or 24 hour format.
timeOnly	boolean	false	Whether to display timepicker only.
stepHour	number	1	Hours to change per step.
stepMinute	number	1	Minutes to change per step.
stepSecond	number	1	Seconds to change per step.
showSeconds	boolean	false	Whether to show the seconds in time picker.
required	boolean	false	When present, it specifies that an input field must be filled out before submitting the form.
showOnFocus	boolean	true	When disabled, datepicker will not be visible with input focus.
showWeek	boolean	false	When enabled, calendar will show week numbers.
showClear	boolean	false	When enabled, a clear icon is displayed to clear the value.
dataType	string	date	Type of the value to write back to ngModel, default is date and alternative is string.
selectionMode	"multiple" \| "range" \| "single"	single	Defines the quantity of the selection, valid values are "single", "multiple" and "range".
maxDateCount	number	null	Maximum number of selectable dates in multiple mode.
showButtonBar	boolean	false	Whether to display today and clear buttons at the footer
todayButtonStyleClass	string	p-button-text	Style class of the today button.
clearButtonStyleClass	string	p-button-text	Style class of the clear button.
autoZIndex	boolean	true	Whether to automatically manage layering.
baseZIndex	number	0	Base zIndex value to use in layering.
panelStyleClass	string	null	Style class of the datetimepicker container element.
panelStyle	any	null	Inline style of the datetimepicker container element.
keepInvalid	boolean	false	Keep invalid value when input blur.
hideOnDateTimeSelect	boolean	true	Whether to hide the overlay on date selection.
touchUI	boolean	false	When enabled, calendar overlay is displayed as optimized for touch devices.
timeSeparator	string	:	Separator of time selector.
focusTrap	boolean	true	When enabled, can only focus on elements inside the calendar.
showTransitionOptions	string	.12s cubic-bezier(0, 0, 0.2, 1)	Transition options of the show animation.
hideTransitionOptions	string	.1s linear	Transition options of the hide animation.
tabindex	number	null	Index of the element in tabbing order.
minDate	Date	null	The minimum selectable date.
maxDate	Date	null	The maximum selectable date.
disabledDates	Date[]	null	Array with dates that should be disabled (not selectable).
disabledDays	number[]	null	Array with weekday numbers that should be disabled (not selectable).
yearRange	string	null	The range of years displayed in the year drop-down in (nnnn:nnnn) format such as (2000:2020).
showTime	boolean	null	Whether to display timepicker.
responsiveOptions	CalendarResponsiveOptions[]	null	An array of options for responsive design.
numberOfMonths	number	null	Number of months to display.
firstDayOfWeek	number	null	Defines the first of the week for various date calculations.
locale	LocaleSettings	null
view	CalendarTypeView	null	Type of view to display, valid values are "date" for datepicker and "month" for month picker.
defaultDate	Date	null	Set the date to highlight on first opening if the field is blank.

Emitters #

Defines emit that determine the behavior of the component based on a given condition or report the actions that the component takes.

name	parameters	description
onFocus	event : Event	Callback to invoke on focus of input field.
onBlur	event : Event	Callback to invoke on blur of input field.
onClose	event : AnimationEvent_2	Callback to invoke when date panel closed.
onSelect	value : Date	Callback to invoke on date select.
onClear	value : any	Callback to invoke when input field cleared.
onInput	value : any	Callback to invoke when input field is being typed.
onTodayClick	value : Date	Callback to invoke when today button is clicked.
onClearClick	value : any	Callback to invoke when clear button is clicked.
onMonthChange	event : CalendarMonthChangeEvent	Callback to invoke when a month is changed using the navigators.
onYearChange	event : CalendarYearChangeEvent	Callback to invoke when a year is changed using the navigators.
onClickOutside	value : any	Callback to invoke when clicked outside of the date panel.
onShow	value : any	Callback to invoke when datepicker panel is shown.

Templates #

Defines the templates used by the component.

name	parameters	description
date	context : { $implicit: Date, // Date value of the component. }	Custom header template.
decade	context : { $implicit: Date, // An array containing the start and and year of a decade to display at header of the year picker. }	Custom decade template
disabledDate	null	Custom disabled date template.
header	null	Custom header template.
previousicon	null	Custom previous icon template.
nexticon	null	Custom next icon template.
triggericon	null	Custom dropdown trigger icon template.
clearicon	null	Custom clear icon template.
decrementicon	null	Custom decrement icon template.
incrementicon	null	Custom increment icon template.
footer	null	Custom footer template.

Events #

Defines the custom events used by the component's emitters.

CalendarYearChangeEvent #

Custom Calendar year change event.

name	type	description
month	number	New month.
year	number	New year.

CalendarMonthChangeEvent #

Custom Calendar month change event.

name	type	description
month	number	New month.
year	number	New year.

Interfaces #

Defines the custom interfaces used by the module.

LocaleSettings #

Locale settings options.

name	type	description
firstDayOfWeek	number	Day value.
dayNames	string[]	Day names.
dayNamesShort	string[]	Shortened day names.
dayNamesMin	string[]	Minimum days names.
monthNames	string[]	Month names.
monthNamesShort	string[]	Shortened month names.
today	string	Value of today date string.
clear	string	Clear.
dateFormat	string	Date format.
weekHeader	string	Week header.

Month #

Month interface.

name	type	description
month	number	Mont value.
year	number	Year value.
dates	Date[]	Array of dates.
weekNumbers	number[]	Array of week numbers.

CalendarResponsiveOptions #

Custom Calendar responsive options metadata.

name	type	description
breakpoint	string	Breakpoint for responsive mode. Exp;
numMonths	number	The number of visible months on breakpoint.

Types #

Defines the custom types used by the module.

CalendarTypeView #

values
"date" \| "month" \| "year"

NavigationState #

values
{ "backward": "boolean", "button": "boolean" }

Wk	Su	Mo	Tu	We	Th	Fr	Sa
47						1	2
48	3	4	5	6	7	8	9
49	10	11	12	13	14	15	16
50	17	18	19	20	21	22	23
51	24	25	26	27	28	29	30
52	31

Wk	Su	Mo	Tu	We	Th	Fr	Sa
47						1	2
48	3	4	5	6	7	8	9
49	10	11	12	13	14	15	16
50	17	18	19	20	21	22	23
51	24	25	26	27	28	29	30
52	31

Wk	Su	Mo	Tu	We	Th	Fr	Sa
47						1	2
48	3	4	5	6	7	8	9
49	10	11	12	13	14	15	16
50	17	18	19	20	21	22	23
51	24	25	26	27	28	29	30
52	31