What does the component do?

A calendar is a component that allows users to display and select date information.

When should the component be used?

• To provide users with an easy way to view and manage date-dependent information like appointments.
• To enable the selection of date ranges for bookings or planning.
• To display recurring events and their patterns.

Rules

• Individual months or entire years can be displayed.
• If the calendar is used in the date picker, only one date can be selected.
• If the calendar is used standalone, several dates can be selected.
• Individual days can have several statuses.

Playground

The <sbb-calendar> component displays a calendar that allows the user to select a date.

This is used internally in the datepicker component, but it can be used on its own.

<sbb-calendar></sbb-calendar>

Slots and day customization

The component uses the <sbb-calendar-day> component to render day cells.

Consumers can override this behavior by slotting their own customized <sbb-calendar-day>,
mainly if some extra content is needed.
The slot name is mandatory, and it requires a date in ISO8601 format (e.g. 2025-01-01).

<sbb-calendar-day slot="2025-01-01"></sbb-calendar-day>

The <sbb-calendar> creates its own slots based on the month to be displayed;
during initialization, the month is the current one (if there's no selected date).
So for the first render, the slotted <sbb-calendar-day> elements must match that month.
For wide mode, also the following one must be taken into account.

Each time the month changes due to user interaction with the previous/next month buttons,
or via selecting a different year and then a month, a monthchange event is emitted, typed as SbbMonthChangeEvent.
The event has a range: Day[] property, which can be accessed to have information about the days to render.
Consumers can listen to this event to dynamically create and slot the <sbb-calendar-day>s of the chosen month.

/* Custom CSS for the extra content */
.my-custom-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  color: light-dark(var(--sbb-color-metal), var(--sbb-color-smoke));
}

<!-- Slot days based on the current date, or the selected one if available.-->
<sbb-calendar selected="2025-01-15" @monthchange="(event) => monthChangeHandler(event)">
  <sbb-calendar-day slot="2025-01-01">
    <span class="sbb-text-xxs my-custom-content"> 19.99 </span>
  </sbb-calendar-day>
  <sbb-calendar-day slot="2025-01-02">
    <span class="sbb-text-xxs my-custom-content"> 9.99 </span>
  </sbb-calendar-day>
  ...
  <sbb-calendar-day slot="2025-01-31">
    <span class="sbb-text-xxs my-custom-content"> 99.99 </span>
  </sbb-calendar-day>
</sbb-calendar>

function monthChangeHandler(e: SbbMonthChangeEvent): void {
  const calendar = e.target;
  // Remove slotted days to keep the DOM clean.
  Array.from(calendar.children).forEach((e) => e.remove());
  // Add the new days
  e.range.map((day) => {
    const child = document.createElement('sbb-calendar-day');
    // The day.value property is the date in ISO8601 format,
    // the correct one for the `<sbb-calendar-day>`'s slot property.
    child.setAttribute('slot', day.value);
    calendar.appendChild(child);
  });
}

States

The <sbb-calendar-day> component has a current state, which is set if the slot name matches the current day.

Also, it has other states based on the properties of the parent <sbb-calendar>.
The disabled and the crossed-out states are based on the value of the min, max and dateFilter properties,
while the selected matches the parent selected properties, including the multiple variant.

Configuration

It's possible to set a date using the dateSelected property. Also, it's possible to place limits on the selection
using the two properties named min and max. For these three properties, the accepted formats are:

• Date objects
• ISO String
• Unix Timestamp (number of seconds since Jan 1, 1970)

It's recommended to set the time to 00:00:00.

<sbb-calendar min="1599955200" max="1699920000" selected="1649980800"></sbb-calendar>

By default, the component takes, in order of priority,
the dateSelected property or the current date to calculate which month it has to show.
It's possible to move to the previous/next month using the two buttons at the top of the component.

It's also possible to select a specific date by clicking on the month label between the buttons:
this action opens a list of twenty-four selectable years, and, after the year selection, the list of months of that year.
Clicking on an element will set the month and restore the first view, allowing to select the desired day.

The <sbb-calendar> can be directly displayed in one of these modalities using the view property (default: day).

<sbb-calendar selected="1585699200" view="month"></sbb-calendar>

<sbb-calendar selected="1585699200" view="year"></sbb-calendar>

The <sbb-calendar> uses two different components to render years and months in their view,
named <sbb-calendar-month> and <sbb-calendar-year>.
These are 'internal-use-only' components, and they are not meant to be used by consumers.

Unwanted dates can be filtered out using the dateFilter property.
Note that the dateFilter function should not be used as a replacement for the min and max properties.
The dateFilter is applied in all the views, so if some months or years are not allowed they will be displayed as disabled in the corresponding view.

/** Returns only working days (Mon-Fri). */
const dateFilterFn: (d: Day) => boolean = d.getDay() !== 6 && d.getDay() !== 0;

<sbb-calendar .dateFilter="${dateFilterFn}"></sbb-calendar>

Multiple mode

By default, the component allows selecting a single date:
this behavior can be changed by setting the multiple attribute to true.
In this case the selected property, if set, must be an array; moreover, the days of the week become clickable,
allowing to select an entire column (e.g. all the Mondays, all the Tuesdays and so on).

<sbb-calendar multiple></sbb-calendar>

If the week-numbers property is set, the ISO week dates are also clickable, allowing to select all the days in the week.

<sbb-calendar multiple week-numbers></sbb-calendar>

Style

The component displays by default a single month in the day view, or a list of twenty-four years in the year view,
or a list of months in the month view;
however, setting the wide property to true it's possible to duplicate the view, showing, respectively, two consecutive months or
two sets of twenty-four years or the list of the twelve months for two consecutive years.

<sbb-calendar wide="true" selected="1699920000"></sbb-calendar>

It's also possible to change the orientation of dates by setting the orientation property to vertical.
In this variant, the weekdays are displayed on the left side of the component and the days progress along the vertical direction.
This visual change is applied only to the day view.

<sbb-calendar orientation="vertical"></sbb-calendar>

In both orientations, the week days are always displayed;
using the week-numbers property, it's possible to display the ISO week dates perpendicularly to week days,
so on the left side in horizontal and on top in vertical.

<sbb-calendar week-numbers></sbb-calendar>

<sbb-calendar orientation="vertical" week-numbers></sbb-calendar>

Two more components, named <sbb-calendar-weeknumber> and <sbb-calendar-weekday>, are used to render
a single week number and a single week day cell.
These are 'internal-use-only' components too, and they are not meant to be used by consumers.

Events

Consumers can listen to the dateselected event on the <sbb-calendar> component to intercept the selected date
which can be read from event.detail.
Check the Slot and day customization paragraph
for more information about the monthchange event.

Keyboard interaction

It's possible to move within the component using the keyboard.

The days disabled due to the presence of the min, max and dateFilter properties are taken into account: for example,
pressing the <kbd>Home</kbd> when the first day of the month is disabled will result in moving to the first non-disabled day.

Horizontal orientation

Vertical orientation

Accessibility

For accessibility purposes, the component is rendered as a native table element and each day is a button.

API Documentation

class: SbbCalendarDayElement, sbb-calendar-day

Properties

Methods

Slots

class: SbbCalendarElement, sbb-calendar

Properties

Methods

Events

Slots

class: SbbCalendarMonthElement, sbb-calendar-month

Properties

Methods

class: SbbCalendarWeekdayElement, sbb-calendar-weekday

Properties

Methods

class: SbbCalendarWeeknumberElement, sbb-calendar-weeknumber

Properties

Methods

class: SbbCalendarYearElement, sbb-calendar-year

Properties

Methods