Calendar
Examples
Month & Day Labels
Showing Adjacent Dates
Multiple Selection
Range Selection
Calendar interface
Mode Display
With Borders
Localizing the Calendar
Importing
Slots
Properties
Events
Methods
Custom Properties
Parts
Dependencies

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="multiple" class="calendar-preview"
  format="YYYY-MM-DD"
  show-adjacent-dates
>
  <div slot="footer"></div>
</p-calendar>

<script>

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

  calendar.value = [
    '2024-09-11',
    '2024-10-11',
  ];



</script>

Examples

Month & Day Labels

Month and day labels can be customized using the month-labels and day-labels attributes. Note that month names are localized automatically based on the component’s lang attribute, falling back to the document language.

<p-calendar month-labels="short" day-labels="narrow"
  format="YYYY-MM-DD"
>
</p-calendar>

Showing Adjacent Dates

By default, only dates in the target month are shown. You can fill the grid with adjacent dates using the show-adjacent-dates attribute.

<p-calendar show-adjacent-dates></p-calendar>

Multiple Selection

One or more dates can be selected by setting the value property. An array of dates is accepted and the selection does not have to be continuous.

<p-calendar class="calendar-multiple-selection" type="multiple"></p-calendar>

<script>
  const calendar = document.querySelector('.calendar-multiple-selection');
  const today = new Date();

  calendar.value = [
    new Date(today.getFullYear(), today.getMonth(), 12),
    new Date(today.getFullYear(), today.getMonth(), 14),
    new Date(today.getFullYear(), today.getMonth(), 17),
    new Date(today.getFullYear(), today.getMonth(), 19)
  ];
</script>

Range Selection

One or more dates can be selected by setting the value property. An array of dates is accepted and the selection does not have to be continuous. When the type attribute is set to range, the selected range of dates is highlighted on the calendar.

<p-calendar class="calendar-range-selection" type="range"></p-calendar>

<script>
  const calendar = document.querySelector('.calendar-range-selection');
  const today = new Date();

  calendar.value = [
    new Date(today.getFullYear(), today.getMonth(), 12),
    new Date(today.getFullYear(), today.getMonth(), 19)
  ];
</script>

Calendar interface

The calendar component will render different grid based on the value of the interface attribute, which can be set to "day", "month". The default interface is "day".

When the interface is "day", the calendar renders a grid of days in the month. The grid has seven columns (for each day of the week) and as many rows as necessary to display the days of the month. The days are displayed in a 7xN grid, with the current day highlighted.

When the interface is "month", the calendar renders a grid of months in the year. The grid has 4 columns and as many rows as necessary to display the months of the year. The months are displayed in a 4xN grid, with the current month highlighted.

<p-calendar type="range" interface="month" class="calendar-interface"
  format="YYYY-MM"
>
  <div slot="footer"></div>
</p-calendar>

<script>

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

  calendar.value = [
    '2024-09',
    '2024-09',
  ];


</script>

Mode Display

The mode property determines how the calendar is displayed. When set to inline, the calendar is displayed inline with the rest of the content, rather than in a popup (default).

<p-calendar class="calendar-mode-inline" mode="inline"></p-calendar>

<script>
  const calendar = document.querySelector('.calendar-mode-inline');
  const today = new Date();

  calendar.value = [
    new Date(today.getFullYear(), today.getMonth(), 12),
    new Date(today.getFullYear(), today.getMonth(), 19)
  ];
</script>

With Borders

To add a border, set the --border-width custom property. You can further customize the border with --border-color and --border-radius.

<p-calendar style="--border-width: 1px;"></p-calendar>

Localizing the Calendar

By default, the calendar will use the document’s locale. You can use the lang attribute to change this.

<p-calendar lang="es"></p-calendar>

[component-metadata:p-calendar]

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.2.15/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.2.15/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	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 \|`YY`it year \| \| undefined \| `YYYY`t year \| \| undefined `M`numeric (0–11) \| \| undefined \|`MM`umeric (00–11) \| \| undefined \| `MMM`breviated \| \| undefined \| `MMMM`ll \| \| undefined `D`month, numeric (1–31) \| \| undefined \|`DD`onth, numeric (01–31) \| \| undefined `d`week, numeric (0–6) \| \| undefined \|`dd`eek, numeric (Su-Sa) \| \| undefined \| `ddd`ek, abbreviated \| \| undefined \| `dddd`ek, full \| \| undefined `H`umeric, 24-hour (0–23) \| \| undefined \|`HH`meric, 24-hour (00–23) \| \| undefined `h`umeric, 12-hour (1–12) \| \| undefined \|`hh`meric, 12-hour (01–12) \| \| undefined `m` numeric (0–59) \| \| undefined \|`mm`numeric (00–59) \| \| undefined `s` numeric (0–59) \| \| undefined \|`ss`numeric (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 to`multiple`, 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>