Calendar

An always-visible month grid for choosing a date or a date range, kept in sync with a native date input.

Class name	Type	Description
`calendarplf:calendar`	Component	Wraps the date input and the view
`calendar-viewplf:calendar-view`	Part	The box the script adds and fills, or an empty, hidden one the page places
`calendar-jumpplf:calendar-jump`	Part	The month and year row the script adds, with two months
`calendar-monthsplf:calendar-months`	Part	The months the script adds
`calendar-month-viewplf:calendar-month-view`	Part	A month the script adds
`calendar-headerplf:calendar-header`	Part	A month's header the script adds
`calendar-navigationplf:calendar-navigation`	Part	The month controls the script adds
`calendar-previousplf:calendar-previous`	Part	The previous-month button the script adds
`calendar-nextplf:calendar-next`	Part	The next-month button the script adds
`calendar-chevronplf:calendar-chevron`	Part	A month button's arrow the script adds
`calendar-captionplf:calendar-caption`	Part	A month's title button the script adds, with two months
`calendar-month-pickerplf:calendar-month-picker`	Part	The month select the script adds
`calendar-yearplf:calendar-year`	Part	The year input the script adds
`calendar-gridplf:calendar-grid`	Part	A month's day table the script adds
`calendar-weekdayplf:calendar-weekday`	Part	A weekday heading the script adds
`calendar-cellplf:calendar-cell`	Part	A day's cell the script adds
`calendar-dayplf:calendar-day`	Part	A day button the script adds
`calendar-footerplf:calendar-footer`	Part	The Today and Clear buttons the script adds
`calendar-statusplf:calendar-status`	Part	The selection status the script adds
`calendar-outsideplf:calendar-outside`	Modifier	An inert day of the next or previous month the script adds, with two months

Default

Appointment date

October 13 is unavailable. Dates are limited to 2026–2027.

<div class="calendar" data-plf-calendar data-plf-today="2026-10-04" data-plf-disabled-dates="2026-10-13">
  <label class="field" for="calendar-appointment">
    <span class="field-label">Appointment date</span>
    <input class="input" id="calendar-appointment" type="date" value="2026-10-04" min="2026-01-01" max="2027-12-31" aria-describedby="calendar-appointment-help">
  </label>
  <p class="field-help" id="calendar-appointment-help">October 13 is unavailable. Dates are limited to 2026–2027.</p>
</div>

<div class="plf:calendar" data-plf-calendar data-plf-today="2026-10-04" data-plf-disabled-dates="2026-10-13">
  <label class="plf:field" for="calendar-appointment">
    <span class="plf:field-label">Appointment date</span>
    <input class="plf:input" id="calendar-appointment" type="date" value="2026-10-04" min="2026-01-01" max="2027-12-31" aria-describedby="calendar-appointment-help">
  </label>
  <p class="plf:field-help" id="calendar-appointment-help">October 13 is unavailable. Dates are limited to 2026–2027.</p>
</div>

Range

A range calendar has no native input, so nothing is submitted; read its value from plf:calendar:change.

<div class="calendar" data-plf-calendar data-plf-mode="range" data-plf-month-count="2" data-plf-today="2026-10-04" data-plf-start="2026-10-08" data-plf-end="2026-10-14"></div>

<div class="plf:calendar" data-plf-calendar data-plf-mode="range" data-plf-month-count="2" data-plf-today="2026-10-04" data-plf-start="2026-10-08" data-plf-end="2026-10-14"></div>

Locale

التاريخ

<div class="calendar" data-plf-calendar data-plf-locale="ar" data-plf-today="2026-10-04" dir="rtl" lang="ar">
  <label class="field" for="calendar-arabic">
    <span class="field-label">التاريخ</span>
    <input class="input" id="calendar-arabic" type="date">
  </label>
</div>

<div class="plf:calendar" data-plf-calendar data-plf-locale="ar" data-plf-today="2026-10-04" dir="rtl" lang="ar">
  <label class="plf:field" for="calendar-arabic">
    <span class="plf:field-label">التاريخ</span>
    <input class="plf:input" id="calendar-arabic" type="date">
  </label>
</div>

Calendar needs JavaScript and is an extension: the Full script and Full CSS leave it out. The Full script (pelatform-ui.min.js) and the extension scripts after it start every component on page load, with no code of your own; with Core and single files, the last line starts them. For markup you add later, see Dynamic content.

<link rel="stylesheet" href="pelatform-ui.min.css">
<link rel="stylesheet" href="extensions/calendar.min.css">
<script src="pelatform-ui.min.js" defer></script>
<script src="extensions/calendar.min.js" defer></script>

<link rel="stylesheet" href="core/pelatform-ui-core.min.css">
<link rel="stylesheet" href="components/button.min.css">
<link rel="stylesheet" href="components/form.min.css">
<link rel="stylesheet" href="components/select.min.css">
<link rel="stylesheet" href="extensions/calendar.min.css">
<script src="core/pelatform-ui-core.min.js" defer></script>
<script src="components/select.min.js" defer></script>
<script src="extensions/calendar.min.js" defer></script>
<script>document.addEventListener('DOMContentLoaded', () => PLF.init());</script>

<link rel="stylesheet" href="pelatform-ui.prefixed.min.css">
<link rel="stylesheet" href="extensions/calendar.prefixed.min.css">
<script src="pelatform-ui.min.js" defer></script>
<script src="extensions/calendar.min.js" defer></script>

<link rel="stylesheet" href="core/pelatform-ui-core.prefixed.min.css">
<link rel="stylesheet" href="components/button.prefixed.min.css">
<link rel="stylesheet" href="components/form.prefixed.min.css">
<link rel="stylesheet" href="components/select.prefixed.min.css">
<link rel="stylesheet" href="extensions/calendar.prefixed.min.css">
<script src="core/pelatform-ui-core.min.js" defer></script>
<script src="components/select.min.js" defer></script>
<script src="extensions/calendar.min.js" defer></script>
<script>document.addEventListener('DOMContentLoaded', () => PLF.init());</script>

With ESM imports, import Calendar from @pelatform/ui/extensions/calendar and call use(Calendar) before init().

Hooks

Dates are YYYY-MM-DD and months YYYY-MM. Inside a date picker, an option may also sit on the picker’s container.

Attribute	Purpose
`data-plf-calendar`	The `calendar` container
`data-plf-calendar-view`	Optional; on an empty, hidden `calendar-view`, places the calendar there instead of after the container’s content
`data-plf-mode`	`single` (default) or `range`
`data-plf-value`	The initial date without an input
`data-plf-start`, `data-plf-end`	The initial range
`data-plf-month`	The first month shown; the selected or current month by default
`data-plf-month-count`	`1` (default) or `2`; two months show one below the `md` breakpoint
`data-plf-locale`	A language tag such as `id`, `en-GB` or `ar`, for month and day names; any locale the browser’s `Intl` knows. The root’s `lang`, the page’s `lang`, then `en` by default; right to left follows `dir`
`data-plf-week-starts-on`	`0` (Sunday) to `6`; `1` (Monday) by default
`data-plf-min`, `data-plf-max`	Inclusive bounds; the input’s `min` and `max` by default
`data-plf-disabled-dates`	Comma-separated unavailable dates
`data-plf-today`	Replaces today’s date, for a fixed example

Methods

Method	Behavior
`PLF.Calendar.getOrCreateInstance(element, options)`	Returns the instance, creating it for valid markup; `options` (`mode`, `value`, `month`, `monthCount`, `locale`, `weekStartsOn`, `min`, `max`, `disabledDates`, `today`) override the attributes
`PLF.Calendar.getInstance(element)`	Returns the instance or `null`
`instance.getState()`	Returns `{mode, value, month, monthCount, focusedDate, locale, weekStartsOn, min, max, disabledDates, today}`
`instance.setValue(value)`	Selects a date, `null`, or a range `{start, end}`; returns `false` when invalid, unchanged or canceled
`instance.setMonth(month)`	Shows a month; returns `false` when out of bounds, unchanged or canceled
`instance.focusDate(date)`	Moves focus to a date, changing the month when needed
`instance.clear()`	Removes the selection
`instance.destroy()`	Removes the generated grid and listeners; the native input keeps its value

Events

Event	When
`plf:calendar:before-change`, `plf:calendar:change`	Before and after a new selection; the first is cancelable
`plf:calendar:before-month-change`, `plf:calendar:month-change`	Before and after another month is shown; the first is cancelable

Each event’s detail:

Property	Value
`instance`	The Calendar instance
`trigger`	The control used, such as a day or the Today button, or `null` from a method
`reason`	`select`, `navigation`, `keyboard`, `clear`, `input` or `api`; `trigger` from a Date Picker
`previousState`	The state before the change, shaped like `getState()`
`state`	The state after the change

Keyboard

Key	Action
Left Arrow, Right Arrow	Move one day; reversed right to left
Up Arrow, Down Arrow	Move one week
Home, End	Move to the first or last day of the week
Page Up, Page Down	Move one month; with Shift, one year
Enter, Space	Select the focused date

CSS variables

Variable	Default
`--plf-calendar-width`	`20rem` (320px); `40rem` (640px) with two months
`--plf-calendar-padding`	`--plf-space-3`, `0.75rem` (12px)
`--plf-calendar-border`	`--plf-color-border-subtle`
`--plf-calendar-radius`	`--plf-radius-lg`, `0.5rem` (8px)
`--plf-calendar-bg`, `--plf-calendar-color`	Transparent, `--plf-color-text`
`--plf-calendar-day-height`	`--plf-control-height-md`, `2.25rem` (36px); `--plf-control-height-sm`, `2rem` (32px), in a Date Picker
`--plf-calendar-hover-bg`	`--plf-color-surface-muted`
`--plf-calendar-selected-bg`, `--plf-calendar-selected-color`	`--plf-color-primary`, `--plf-color-on-primary`
`--plf-calendar-range-bg`	`--plf-color-primary-subtle`, between the range ends
`--plf-calendar-disabled-opacity`	`0.5`