import Calendar from 'primevue/calendar';
<script src="https://unpkg.com/primevue@^3/core/core.min.js"></script>
<script src="https://unpkg.com/primevue@^3/calendar/calendar.min.js"></script>
Two-way value binding is defined using the standard v-model directive referencing to a Date property.
<Calendar v-model="value" />
export default {
data() {
return {
value: null
}
}
}
Calendar is displayed in a popup by default and inline property needs to be enabled for inline mode.
<Calendar v-model="value" :inline="true" />
By default calendar allows selecting one date only whereas multiple dates can be selected by setting selectionMode to multiple. In this case calendar updates the value with an array of dates where optionally number of selectable dates can be restricted with maxDateCount property. Third alternative is the range mode that allows selecting a range based on an array of two values where first value is the start date and second value is the end date.
<Calendar v-model="value" selectionMode="single || multiple || range" />
Default date format is mm/dd/yy, to customize this use dateFormat property or define it at
<Calendar v-model="value" dateFormat="dd.mm.yy" />
Following options can be a part of the format.
TimePicker is enabled with showTime property and 24 (default) or 12 hour mode is configured using hourFormat option. If you need to use the time picker as standalone, use the timeOnly property.
<Calendar v-model="value" :showTime="true" />
<Calendar v-model="value" :showTime="true" hourFormat="12" />
<Calendar v-model="value" :showTime="true" :timeOnly="true" />
To disable entering dates manually, set manualInput to false and to restrict selectable dates with the minDate and maxDate options.
<Calendar v-model="value" :minDate="minDateValue" maxDate="maxDateValue" />
To disable specific dates or days, restrict selectable dates use disabledDates and/or disabledDays options.
<Calendar v-model="value" :disabledDates="invalidDates" :disabledDays="[0,6]" />
Button bar displays today and clear buttons and enabled using showButtonBar property.
<Calendar v-model="value" :showButtonBar="true" />
Displaying multiple months is enabled by setting numberOfMonths property to a value greater than 1.
<Calendar v-model="value" :numberOfMonths="3" />
Locale for different languages and formats is defined globally, refer to the
Calendar UI accepts custom content using header and footer templates.
<Calendar v-model="value">
<template #header>Header Content</template>
<template #footer>Footer Content</template>
</Calendar>
In addition, cell contents can be templated using a template named "date". This is a handy feature to highlight specific dates. Note that the date property of the slot props passed to the template is not a date instance but a metadata object to represent a Date with "day", "month" and "year" properties. Example below changes the background color of dates between 10th and 15th of each month.
<Calendar v-model="value">
<template #date="slotProps">
<strong v-if="slotProps.date.day > 10 && slotProps.date.day < 15" class="special-day">{{slotProps.date.day}}</strong>
<template v-else>{{slotProps.date.day}}</template>
</template>
</Calendar>
.special-day {
text-decoration: line-through;
}
Month picker is used to select month and year only without the date, set view mode as "month" to activate month picker.
<Calendar v-model="value" view="month" dateFormat="mm/yy" />
Similar to the month picker, year picker can be used to select years only. Set view to "year" to display the year picker.
<Calendar v-model="value" view="year" dateFormat="yy" />
Touch UI mode displays the calendar overlay at the center of the screen as optimized for touch devices.
<Calendar v-model="value" :touchUI="true" />
Any property such as name and placeholder are passed to the underlying input element. Following are the additional properties to configure the component.
| Name | Type | Default | Description |
|---|---|---|---|
| modelValue | any | null | Value of the component. |
| selectionMode | string | single | Defines the quantity of the selection, valid values are "single", "multiple" and "range". |
| dateFormat | string | null | Format of the date. Defaults to PrimeVue |
| inline | boolean | false | When enabled, displays the calendar as inline instead of an overlay. |
| disabled | boolean | false | When specified, disables the component. |
| readonly | boolean | false | When present, it specifies that an input field is read-only. |
| 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 | pi pi-calendar | Icon of the calendar button. |
| numberOfMonths | number | 1 | Number of months to display. |
| responsiveOptions | any | null | An array of options for responsive design. |
| view | string | date | Type of view to display, valid values are "date", "month" and "year". |
| touchUI | boolean | false | When enabled, calendar overlay is displayed as optimized for touch devices. |
| 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. |
| minDate | Date | null | The minimum selectable date. |
| maxDate | Date | null | The maximum selectable date. |
| disabledDates | array; | null | Array with dates to disable. |
| disabledDays | array | null | Array with disabled weekday numbers. |
| maxDateCount | number | null | Maximum number of selectable dates in multiple mode. |
| showOnFocus | boolean | true | When disabled, datepicker will not be visible with input focus. |
| autoZIndex | boolean | true | Whether to automatically manage layering. |
| baseZIndex | number | 0 | Base zIndex value to use in layering. |
| showButtonBar | boolean | false | Whether to display today and clear buttons at the footer |
| shortYearCutoff | string | +10 | The cutoff year for determining the century for a date. |
| showTime | boolean | false | Whether to display timepicker. |
| timeOnly | boolean | false | Whether to display timepicker only. |
| hourFormat | string | 24 | Specifies 12 or 24 hour format. |
| 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. |
| hideOnDateTimeSelect | boolean | false | Whether to hide the overlay on date selection when showTime is enabled. |
| hideOnRangeSelection | boolean | false | Whether to hide the overlay on date selection is completed when selectionMode is range. |
| timeSeparator | string | : | Separator of time selector. |
| showWeek | boolean | false | When enabled, calendar will show week numbers. |
| manualInput | boolean | true | Wheter to allow prevents entering the date manually via typing. |
| appendTo | string | body | A valid query selector or an HTMLElement to specify where the overlay gets attached. Special keywords are "body" for document body and "self" for the element itself. |
| disabled | boolean | false | When present, it specifies that the element should be disabled. |
| readonly | boolean | false | When present, it specifies that an input field is read-only. |
| placeholder | string | null | Default text to display when no option is selected. |
| id | string | null | Unique identifier of the element. |
| inputId | string | null | Style class of the component input field. |
| inputStyle | any | null | Inline style of the input field. |
| inputClass | string | null | Style class of the input field. |
| inputProps | object | null | Uses to pass all properties of the HTMLInputElement to the focusable input element inside the component. |
| panelClass | string | null | Style class of the overlay panel. |
| panelStyle | string | null | Inline style of the overlay panel. |
| panelProps | object | null | Uses to pass all properties of the HTMLDivElement to the overlay panel inside the component. |
Any valid event such as focus, blur and input are passed to the underlying input element. Following are the additional events to configure the component.
| Name | Parameters | Description |
|---|---|---|
| input | event: Input Event | Callback to invoke when input field is being typed. |
| date-select | value: Selected value | Callback to invoke when a date is selected. |
| show | - | Callback to invoke when datepicker panel is shown. |
| hide | - | Callback to invoke when datepicker panel is hidden. |
| today-click | date: Today as a date instance | Callback to invoke when today button is clicked. |
| clear-click | event: Click event | Callback to invoke when clear button is clicked. |
| month-change |
event.month: New month event.year: New year |
Callback to invoke when a month is changed using the navigators. |
| year-change |
event.month: New month event.year: New year |
Callback to invoke when a year is changed using the navigators. |
| focus | event: Focus event | Callback to invoke on focus of input field. |
| blur |
event.originalEvent: Blur event event.value: Input value |
Callback to invoke on blur of input field. |
| keydown | event: Keyboard event | Callback to invoke when a key is pressed. |
| Name | Parameters |
|---|---|
| header | - |
| footer | - |
| date | date: Value of the component |
| decade | years: An array containing the start and and year of a decade to display at header of the year picker |
Following is the list of structural style classes, for theming classes visit
| 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
chooseDate key of the aria property from the
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>
<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. |
None.