Calendar is an input component to select a date.
import { CalendarModule } from 'primeng/calendar';
Two-way value binding is defined using the standard ngModel directive referencing to a Date property.
<p-calendar [(ngModel)]="date"></p-calendar>
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>
Default date format is mm/dd/yy which can be customized using the dateFormat property. Following options can be a part of the format.
<p-calendar [(ngModel)]="date" dateFormat="dd.mm.yy"></p-calendar>
Locale for different languages and formats is defined globally, refer to the PrimeNG Locale configuration for more information.
An additional icon is displayed next to the input field when showIcon is present.
<p-calendar [(ngModel)]="date" [showIcon]="true"></p-calendar>
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>
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>
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>
When showButtonBar is present, today and clear buttons are displayed at the footer.
<p-calendar [(ngModel)]="date" [showButtonBar]="true"></p-calendar>
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 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>
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>
Number of months to display is configured with the numberOfMonths property.
<p-calendar [(ngModel)]="date" [numberOfMonths]="3"></p-calendar>
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>
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>
When touchUI is enabled, overlay is displayed as optimized for touch devices.
<p-calendar [(ngModel)]="date" [touchUI]="true" [readonlyInput]="true"></p-calendar>
Calendar is displayed as a popup by default, add inline property to customize this behavior.
<p-calendar class="max-w-full" [(ngModel)]="date" [inline]="true" [showWeek]="true"></p-calendar>
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. |
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 aria-labelledby="date2"></p-calendar>
<p-calendar aria-label="Date"></p-calendar>
| 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. |
| 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. |
| Key | Function |
|---|---|
| enter | Triggers the button action. |
| space | Triggers the button action. |
| 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 |
| Key | Function |
|---|---|
| enter | Triggers the button action. |
| space | Triggers the button action. |
API defines helper props, events and others for the PrimeNG Calendar module.
| Name | Type | Default | Description |
|---|---|---|---|
| defaultDate | Date | null | Set the date to highlight on first opening if the field is blank. |
| selectionMode | string | single | Defines the quantity of the selection, valid values are "single", "multiple" and "range". |
| style | string | null | Inline style of the component. |
| styleClass | string | null | Style class of the component. |
| inputStyle | string | null | Inline style of the input field. |
| inputStyleClass | string | null | Style class 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. |
| placeholder | string | null | Placeholder text for the input. |
| disabled | boolean | false | When specified, disables the component. |
| dateFormat | string | mm/dd/yy | Format of the date which can also be defined at locale settings. |
| 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. |
| showOnFocus | boolean | true | When disabled, datepicker will not be visible with input focus. |
| showWeek | boolean | false | When enabled, calendar will show week numbers. |
| 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 | null | When specified, prevents entering the date manually with keyboard. |
| shortYearCutoff | string | +10 | The cutoff year for determining the century for a date. |
| minDate | Date | null | The minimum selectable date. |
| maxDate | Date | null | The maximum selectable date. |
| disabledDates | Array<Date> | null | Array with dates that should be disabled (not selectable). |
| disabledDays | Array<number> | null | Array with weekday numbers that should be disabled (not selectable). |
| monthNavigator | boolean | false | Whether the month should be rendered as a dropdown instead of text. Deprecated: Navigator is always on |
| yearNavigator | boolean | false | Whether the year should be rendered as a dropdown instead of text. Deprecated: Navigator is always on. |
| yearRange | string | null | The range of years displayed in the year drop-down in (nnnn:nnnn) format such as (2000:2020). Deprecated: Years are based on decades by default. |
| showTime | boolean | false | Whether to display timepicker. |
| hourFormat | string | 24 | Specifies 12 or 24 hour format. |
| timeOnly | boolean | false | Whether to display timepicker only. |
| timeSeparator | string | : | Separator of time selector. |
| dataType | string | date | Type of the value to write back to ngModel, default is date and alternative is string. |
| required | boolean | false | When present, it specifies that an input field must be filled out before submitting the form. |
| tabindex | number | null | Index of the element in tabbing order. |
| ariaLabelledBy | string | null | Establishes relationships between the component and label(s) where its value should be one or more element IDs. |
| iconAriaLabel | string | null | Defines a string that labels the icon button for accessibility. |
| showSeconds | boolean | false | Whether to show the seconds in time picker. |
| stepHour | number | 1 | Hours to change per step. |
| stepMinute | number | 1 | Minutes to change per step. |
| stepSecond | number | 1 | Seconds to change per step. |
| 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-secondary-button | Style class of the today button. |
| clearButtonStyleClass | string | p-secondary-button | Style class of the clear button. |
| baseZIndex | number | 0 | Base zIndex value to use in layering. |
| autoZIndex | boolean | true | Whether to automatically manage layering. |
| panelStyleClass | string | null | Style class of the datetimepicker container element. |
| panelStyle | object | 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. |
| numberOfMonths | number | 1 | Number of months to display. |
| view | 'date' | 'month' | 'year' | date | Type of view to display, valid values are "date" for datepicker and "month" for month picker. |
| multipleSeparator | string | , | Separator for multiple selection mode. |
| rangeSeparator | string | - | Separator for joining start and end dates on range selection mode. |
| touchUI | boolean | false | When enabled, calendar overlay is displayed as optimized for touch devices. |
| 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. |
| firstDayOfWeek | number | 0 | Defines the first of the week for various date calculations. |
| showClear | boolean | false | When enabled, a clear icon is displayed to clear the value. |
| Name | Parameters | Description |
|---|---|---|
| onSelect | value: Selected value | Callback to invoke when a date is selected. Note that this event is not called when the value is entered from the input manually. |
| onBlur | event: Blur event | Callback to invoke on blur of input field. |
| onFocus | event: Focus event | Callback to invoke on focus of input field. |
| onClose | event: Close event | Callback to invoke when datepicker panel is closed. |
| onShow | event: Animation event | Callback to invoke when datepicker panel is visible. |
| onClickOutside | event: Click event | Callback to invoke when click outside of datepicker panel. |
| onInput | event: Input event | Callback to invoke when input field is being typed. |
| onTodayClick | event: Click event | Callback to invoke when today button is clicked. |
| onClearClick | event: Click event | Callback to invoke when clear button is clicked. |
| onMonthChange | event.month: New month event.year: New year | Callback to invoke when a month is changed using the navigators. |
| onYearChange | event.month: New month event.year: New year | Callback to invoke when a year is changed using the navigators. |
| onClear | - | Callback to invoke when input field is cleared. |
| Name | Parameters |
|---|---|
| header | - |
| footer | - |
| date | $implicit: Value of the component |
| decade | $implicit: An array containing the start and and year of a decade to display at header of the year picker. |
| previousicon | - |
| nexticon | - |
| triggericon | - |
| clearicon | - |
| incrementicon | - |
| decrementicon | - |
| Name | Parameters | Description |
|---|---|---|
| toggle | - | Toggles the visibility of the calendar. |