Calendar

<p-calendar> | PCalendar
Since 1.1.5 stable

Calendar shows a monthly view of the Gregorian calendar, optionally allowing users to interact with dates. 

<p-calendar type="single" class="calendar-preview"
  format="YYYY-MM-DD"
  show-adjacent-dates
  week-starts-with="sunday"
>
  <div slot="footer"></div>
</p-calendar>

<script>

  const calendar = document.querySelector('.calendar-preview');
  const today = new Date();

  calendar.value = [
    '2025-04-09',
  ];

  calendar.addEventListener('p-change', (e) => {
    calendar.value = e.target.value;
  })


</script>

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script Import Bundler React

To import this component from the CDN using a script tag: 

<script type="module" src="https://cdn.jsdelivr.net/npm/pure-uikit@1.6.30/cdn/components/calendar/calendar.js"></script>

To import this component from the CDN using a JavaScript import: 

import 'https://cdn.jsdelivr.net/npm/pure-uikit@1.6.30/cdn/components/calendar/calendar.js';

To import this component using a bundler:

import 'pure-uikit/dist/components/calendar/calendar.js';

To import this component as a React component:

import PCalendar from 'pure-uikit/dist/react/calendar';

Slots

Name Description
footer Optional content to place in the calendar’s footer.
label The input’s label. Alternatively, you can use the label attribute.
prefix Used to prepend a presentational icon or similar element to the calendar.
suffix Used to append a presentational icon or similar element to the calendar.
clear-icon An icon to use in lieu of the default clear icon.
help-text Text that describes how to use the input. Alternatively, you can use the help-text attribute.

Learn more about using slots.

Properties

Name Description Reflects Type Default
closeOnSelect
close-on-select 		Whether to close the calendar when a date is selected. When true, the calendar will close after a date is selected. This attribute only applies when the calendar is in dialog mode and type not “multiple”. boolean false
format The date format to use when formatting the date. The format string is a combination of the following tokens: | Token | Description | |——-|————-| | undefined |YYit year | | undefined | YYYYt year | | undefined Mnumeric (0–11) | | undefined |MMumeric (00–11) | | undefined | MMMbreviated | | undefined | MMMMll | | undefined Dmonth, numeric (1–31) | | undefined |DDonth, numeric (01–31) | | undefined dweek, numeric (0–6) | | undefined |ddeek, numeric (Su-Sa) | | undefined | dddek, abbreviated | | undefined | ddddek, full | | undefined Humeric, 24-hour (0–23) | | undefined |HHmeric, 24-hour (00–23) | | undefined humeric, 12-hour (1–12) | | undefined |hhmeric, 12-hour (01–12) | | undefined m numeric (0–59) | | undefined |mmnumeric (00–59) | | undefined s numeric (0–59) | | undefined |ssnumeric (00–59) | string ""
typing Indicates whether the calendar is in typing mode. Typing mode means that the calendar accepts user input and emits p-input and p-change events when the user types a valid date. When typing mode is false, the calendar does not accept user input and does not emit p-input or p-change events. boolean true
displayLabel The display label to show in the select when no options are selected. Used when the control is not focused. string ""
currentOption The currently selected option. Date undefined
selectedOptions The selected options. Date | Date[] []
name The name of the calendar, submitted as a name/value pair with form data. string ""
_value The current value of the calendar, submitted as a name/value pair with form data. When type is set tomultiple, the value attribute will be a space-delimited list of values based on the dates selected, and the value property will be an array. For this reason, values must not contain spaces. Date | Date[] []
defaultValue The default value of the form control. Primarily used for resetting the form control. Date | Date[] new Date()
size The select’s size. "small" | "medium" | "large" "medium"
placeholder Placeholder text to show as a hint when the select is empty. string ""
maxOptionsVisible
max-options-visible 		The maximum number of selected options to show when multiple is true. After the maximum, ”+n” will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit. number 3
disabled Disables the select control. boolean false
clearable Adds a clear button when the select is not empty. boolean false
open Indicates whether or not the calendar is open. You can toggle this attribute to show and hide the menu, or you can use the show() and hide() methods and this attribute will reflect the select’s open state. boolean false
hoist Enable this option to prevent the calendar from being clipped when the component is placed inside a container with overflow: auto|scroll. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios. boolean false
filled Draws a filled select. boolean false
pill Draws a pill-style select with rounded edges. boolean false
label The calendar’s label. If you need to display HTML, use the label slot instead. string ""
placement The preferred placement of the calendar’s popup. Note that the actual placement may vary as needed to keep the calendar inside of the viewport. "top" | "bottom" "bottom"
helpText
help-text 		The select’s help text. If you need to display HTML, use the help-text slot instead. string ""
form By default, form controls are associated with the nearest containing <form> element. This attribute allows you to place the form control outside of a form and associate it with the form that has this id. The form must be in the same document or shadow root for this to work. string ""
required The select’s required attribute. boolean false
getTag A function that customizes the tags to be rendered when type=multiple. The first argument is the option, the second is the current tag’s index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value. (option: Date, index: number) => TemplateResult | string | HTMLElement -
showToday
show-today 		When true, the calendar will show a button to quickly jump to today’s date. boolean false
mode The mode of the calendar. - “default”: calendar is displayed in a popup. - “inline”: calendar is displayed inline. "default" | "inline" "default"
type The type of selection the calendar allows. - “single”: allows selecting a single date. - “multiple”: allows selecting multiple dates. - “range”: allows selecting a range of dates. "single" | "multiple" | "range" "single"
interface The interface of the calendar. - “day”: a regular calendar for selecting day according to Calendar type . - “month”: a calendar for selecting a month and year according to Calendar type . - “year”: a calendar for selecting a year according to Calendar type . "day" | "month" | "year" "day"
autofocus If true, the calendar will automatically receive focus when it open. This can be useful when using the calendar in a dialog or other scenario where it should receive focus without requiring the user to click on it. boolean false
month The month to render, 1–12/ number -
year The year to render. number -
date The date to render. number -
dayLabels
day-labels 		Determines how day labels are shown, e.g. “M”, “Mon”, or “Monday”. "narrow" | "short" | "long" "short"
monthLabels
month-labels 		Determines how month labels are shown, e.g. “J”, “Jan”, or “January”. "numeric" | "2-digit" | "long" | "short" | "narrow" "long"
showAdjacentDates
show-adjacent-dates 		When true, dates from the previous and next month will also be shown to fill out the grid. boolean false
validity Gets the validity state object - -
validationMessage Gets the validation message - -
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
p-change onPChange Emitted when the control’s value changes. -
p-clear onPClear Emitted when the control’s value is cleared. -
p-input onPInput Emitted when the control receives input. -
p-focus onPFocus Emitted when the control gains focus. -
p-blur onPBlur Emitted when the control loses focus. -
p-show onPShow Emitted when the select’s menu opens. -
p-after-show onPAfterShow Emitted after the select’s menu opens and all animations are complete. -
p-hide onPHide Emitted when the select’s menu closes. -
p-after-hide onPAfterHide Emitted after the select’s menu closes and all animations are complete. -
p-invalid onPInvalid Emitted when the form control has been checked for validity and its constraints aren’t satisfied. -

Learn more about events.

Methods

Name Description Arguments
show() Shows the calendar. -
hide() Hides the calendar. -
checkValidity() Checks for validity but does not show a validation message. Returns true when valid and false when invalid. -
getForm() Gets the associated form, if one exists. -
reportValidity() Checks for validity and shows the browser’s validation message if the control is invalid. -
setCustomValidity() Sets a custom validation message. Pass an empty string to restore validity. message: string
focus() Sets focus on the control. options: FocusOptions
blur() Removes focus from the control. -
goToToday() Moves the calendar to the current month and year. -
goToPreviousMonth() Moves the calendar to the previous month. event: MouseEvent
goToNextMonth() Moves the calendar to the next month. event: MouseEvent
goToPreviousYear() Moves the calendar to the previous year. event: MouseEvent
goToNextYear() Moves the calendar to the next year. event: MouseEvent

Learn more about methods.

Custom Properties

Name Description Default
--border-color The calendar’s border color.
--border-width The calendar’s border width.
--border-radius The border radius of the calendar.

Learn more about customizing CSS custom properties.

Parts

Name Description
calendar The component’s container.
day Targets day cells.
day-label Targets the day labels (the name of the days in the grid).
day-weekend Targets days that fall on weekends.
day-weekday Targets weekdays.
day-current-focus Targets days that are focused (used for keyboard navigation).
day-current-month Targets days in the current month.
day-previous-month Targets days in the previous month.
day-next-month Targets days in the next month.
day-today Targets today.
day-selected Targets selected days.
day-selection-start Targets days that begin a selection.
day-selected-in-range Targets days that are in the middle of a selection when use type=“range”.
day-selection-end Targets days that end a selection.
tag Targets days that selected when use type=“multiple”.

Learn more about customizing CSS parts.

Dependencies

This component automatically imports the following dependencies.

  • <p-icon>
  • <p-icon-button>
  • <p-popup>
  • <p-tag>