DatePicker

DatePicker is an input component to select a date.


import { DatePicker } from 'primeng/datepicker';

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


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

DatePicker 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-datepicker formControlName="date" />
</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.

  • 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-datepicker [(ngModel)]="date" dateFormat="dd.mm.yy" />

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-datepicker [(ngModel)]="date1" [showIcon]="true" inputId="buttondisplay" [showOnFocus]="false" />

<p-datepicker [(ngModel)]="date2" [iconDisplay]="'input'" [showIcon]="true" inputId="icondisplay" />

<p-datepicker [(ngModel)]="date3" [iconDisplay]="'input'" [showIcon]="true" [timeOnly]="true" inputId="templatedisplay">
    <ng-template pTemplate="inputicon" let-clickCallBack="clickCallBack">
        <i class="pi pi-clock" (click)="clickCallBack($event)"></i>
    </ng-template>
</p-datepicker>

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


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

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


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

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-datepicker [(ngModel)]="rangeDates" selectionMode="range" [readonlyInput]="true" />

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


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

A time picker is displayed when showTime is enabled where 12/24 hour format is configured with hourFormat property. In case, only time needs to be selected, add timeOnly to hide the date section.


<p-datepicker inputId="calendar-12h" [(ngModel)]="datetime12h" [showTime]="true" [hourFormat]="12" />

<p-datepicker inputId="calendar-24h" [(ngModel)]="datetime24h" [showTime]="true" [hourFormat]="24" />

<p-datepicker inputId="calendar-timeonly" [(ngModel)]="time" [timeOnly]="true" />

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


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

Specifying view as year in addition to a suitable dateFormat enables the year picker.


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

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


<p-datepicker [(ngModel)]="date" [numberOfMonths]="2" />

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


<p-datepicker [(ngModel)]="date">
    <ng-template pTemplate="date" let-date>
        <strong *ngIf="date.day > 10 && date.day < 15; else elseBlock" style="text-decoration: line-through">{{ date.day }}</strong>
        <ng-template #elseBlock>{{ date.day }}</ng-template>
    </ng-template>
</p-datepicker>

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

WkSuMoTuWeThFrSa
48 1234567
49 891011121314
50 15161718192021
51 22232425262728
52 2930311234

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

A floating label appears on top of the input field when focused. Visit FloatLabel documentation for more information.


<p-floatlabel>
    <p-datepicker [(ngModel)]="value1" inputId="over_label" showIcon iconDisplay="input" />
    <label for="over_label">Over Label</label>
</p-floatlabel>

<p-floatlabel variant="in">
    <p-datepicker [(ngModel)]="value2" inputId="in_label" showIcon iconDisplay="input" />
    <label for="in_label">In Label</label>
</p-floatlabel>

<p-floatlabel variant="on">
    <p-datepicker [(ngModel)]="value3" inputId="on_label" showIcon iconDisplay="input" />
    <label for="on_label">On Label</label>
</p-floatlabel>

IftaLabel is used to create infield top aligned labels. Visit IftaLabel documentation for more information.


<p-floatlabel>
    <p-datepicker [(ngModel)]="value1" inputId="over_label" showIcon iconDisplay="input" />
    <label for="over_label">Over Label</label>
</p-floatlabel>

<p-floatlabel variant="in">
    <p-datepicker [(ngModel)]="value2" inputId="in_label" showIcon iconDisplay="input" />
    <label for="in_label">In Label</label>
</p-floatlabel>

<p-floatlabel variant="on">
    <p-datepicker [(ngModel)]="value3" inputId="on_label" showIcon iconDisplay="input" />
    <label for="on_label">On Label</label>
</p-floatlabel>

DatePicker provides small and large sizes as alternatives to the base.


<p-datepicker [(ngModel)]="value1" size="small" placeholder="Small" showIcon iconDisplay="input" />
<p-datepicker [(ngModel)]="value2" placeholder="Normal" showIcon iconDisplay="input" />
<p-datepicker [(ngModel)]="value3" size="large" placeholder="Large" showIcon iconDisplay="input" />

Specify the variant property as filled to display the component with a higher visual emphasis than the default outlined style.


<p-datepicker [(ngModel)]="date" variant="filled" />

Invalid state style is added using the ng-invalid and ng-dirty class to indicate a failed validation.


<p-datepicker [(ngModel)]="date" class="ng-invalid ng-dirty" />

When disabled is present, the element cannot be edited and focused.


<p-datepicker [(ngModel)]="date" [disabled]="true" />

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 DatePicker 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.

DatePicker 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-datepicker inputId="date1"/>

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

<p-datepicker ariaLabel="Date"/>

Choose Date Button Keyboard Support

KeyFunction
spaceOpens popup and moves focus to the selected date, if there is none focuses on today.
enterOpens popup and moves focus to the selected date, if there is none focuses on today.

Popup Keyboard Support

KeyFunction
escapeCloses the popup and moves focus to the input element.
tabMoves focus to the next focusable element within the popup.
shift + tabMoves focus to the next focusable element within the popup.

Header Buttons Keyboard Support

KeyFunction
enterTriggers the button action.
spaceTriggers the button action.

Date Grid Keyboard Support

KeyFunction
enterSelects the date, closes the popup and moves focus to the input element.
spaceSelects the date, closes the popup and moves focus to the input element.
up arrowMoves focus to the same day of the previous week.
down arrowMoves focus to the same day of the next week.
right arrowMoves focus to the next day.
left arrowMoves focus to the previous day.
homeMoves focus to the first day of the current week.
endMoves focus to the last day of the current week.
page upChanges 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 upChanges the date to previous year in date picker mode. Has no effect in month or year picker
page downChanges 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 downChanges the date to next year in date picker mode. Has no effect in month or year picker

Footer Buttons Keyboard Support

KeyFunction
enterTriggers the button action.
spaceTriggers the button action.