Calendar, also known as DatePicker, is a form component to work with dates.
import { Calendar } from 'primereact/calendar';
Calendar is used a controlled input component with value and onChange properties.
<Calendar value={date} onChange={(e) => setDate(e.value)} />
Default date format is mm/dd/yy which can be customized using the dateFormat property. Following options can be a part of the format.
<Calendar value={date} onChange={(e) => setDate(e.value)} dateFormat="dd/mm/yy" />
Locale based settings such as labels, dateFormat and firstDayOfWeek are derived from the global Locale configuration. In case, a certain calendar needs to be customized, locale property can be used to override the global setting.
<Calendar value={date} onChange={(e) => setDate(e.value)} locale="es" />
An additional icon is displayed next to the input field when showIcon is present.
<Calendar value={date} onChange={(e) => setDate(e.value)} showIcon />
Boundaries for the permitted dates that can be entered are defined with minDate and maxDate properties.
<Calendar id="minmax" value={date} onChange={(e) => setDate(e.value)} minDate={minDate} maxDate={maxDate} readOnlyInput />
In order to choose multiple dates, set selectionMode as multiple. In this mode, the value binding should be an array.
<Calendar value={dates} onChange={(e) => setDates(e.value)} selectionMode="multiple" readOnlyInput />
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.
<Calendar value={dates} onChange={(e) => setDates(e.value)} selectionMode="range" readOnlyInput />
When showButtonBar is present, today and clear buttons are displayed at the footer.
<Calendar value={date} onChange={(e) => setDate(e.value)} showButtonBar />
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.
<Calendar value={datetime12h} onChange={(e) => setDateTime12h(e.value)} showTime hourFormat="12" />
<Calendar value={datetime24h} onChange={(e) => setDateTime24h(e.value)} showTime hourFormat="24" />
<Calendar value={time} onChange={(e) => setTime(e.value)} timeOnly />
Month only picker is enabled by specifying view as month in addition to a suitable dateFormat.
<Calendar value={date} onChange={(e) => setDate(e.value)} view="month" dateFormat="mm/yy" />
Specifying view as year in addition to a suitable dateFormat enables the year picker.
<Calendar value={date} onChange={(e) => setDate(e.value)} view="year" dateFormat="yy" />
Number of months to display is configured with the numberOfMonths property.
<Calendar value={date} onChange={(e) => setDate(e.value)} numberOfMonths={2} />
Custom content can be placed inside date cells with the dateTemplate property that takes a Date as a parameter.
<Calendar value={date} onChange={(e) => setDate(e.value)} dateTemplate={dateTemplate} />
When touchUI is enabled, overlay is displayed as optimized for touch devices.
<Calendar value={date} onChange={(e) => setDate(e.value)} touchUI />
Calendar is displayed as a popup by default, add inline property to customize this behavior.
| Wk | Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|---|
| 43 | 29 | 30 | 31 | 1 | 2 | 3 | 4 |
| 44 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 45 | 12 | 13 | 14 | 15 | 16 | 17 | 18 |
| 46 | 19 | 20 | 21 | 22 | 23 | 24 | 25 |
| 47 | 26 | 27 | 28 | 29 | 30 | 1 | 2 |
<Calendar value={date} onChange={(e) => setDate(e.value)} inline showWeek />
A floating label appears on top of the input field when focused.
<span className="p-float-label">
<Calendar inputId="birth_date" value={date} onChange={(e) => setDate(e.value)} />
<label htmlFor="birth_date">Birth Date</label>
</span>
Invalid state style is added using the p-invalid class to indicate a failed validation.
<Calendar className="p-invalid" />
When disabled is present, the element cannot be edited and focused.
<Calendar disabled />
Compatibility with popular React form libraries.
Formik is a popular library for handling forms in React.
<form onSubmit={formik.handleSubmit} className="flex flex-column gap-2">
<label htmlFor="cal_date">Date</label>
<Toast ref={toast} />
<Calendar
inputId="cal_date"
name="date"
value={formik.values.date}
className={classNames({ 'p-invalid': isFormFieldInvalid('date') })}
onChange={(e) => {
formik.setFieldValue('date', e.target.value);
}}
/>
{getFormErrorMessage('date')}
<Button type="submit" label="Submit" />
</form>
React Hook Form is another popular React library to handle forms.
<Toast ref={toast} />
<Controller
name="date"
control={form.control}
rules={{ required: 'Date is required.' }}
render={({ field, fieldState }) => (
<>
<label htmlFor={field.name}>Date</label>
<Calendar inputId={field.name} value={field.value} onChange={field.onChange} dateFormat="dd/mm/yy" className={classNames({ 'p-invalid': fieldState.error })} />
{getFormErrorMessage(field.name)}
</>
)}
/>
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-monthpicker | Datepicker element in month view. |
| p-monthpicker-month | Month cell in month view mode. |
| p-datepicker-touch-ui | Datepicker element in touch ui 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 chooseDatekey 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 htmlFor="date1">Date</label>
<Calendar inputId="date1" />
<span id="date2">Date</span>
<Calendar aria-labelledby="date2" />
<Calendar aria-label="Date" />
| 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. |