(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Calendar

Overview

  • The Dynamic Calendar component lets users view, select, and interact with dates or date ranges.
  • It supports different visualization modes for navigating days, months, and years.
  • It can display indicators on specific dates to reflect events or important information.
  • It is useful for showing events, appointments, and important dates in applications.

Calendar overview

Specs

Tokens

Token Description
displayName Display name in structure panel.
viewDate Initial month shown (currentMonth, previousMonth, nextMonth).
selectionMode Interaction mode: date or timeframe.
minZoomMode Minimum zoom level.
maxZoomMode Maximum zoom level.
useMockData Enables sample indicator data.
fetchEntityCollectionDataSourceId Data source ID for indicators.
getEntityCollectionHttpRequestParametersMap HTTP parameters map for data requests.
events Configures component events.
ON_CALENDAR_DATETIME_CHANGE (Events) Fires on date or range selection.
ON_INIT (Events) Fires on component initialization.
ON_DESTROY (Events) Fires when component is removed.
visibilityPolicySetId Policy controlling component visibility.
displayConditions Rules to show/hide the calendar.
id Unique identifier for programmatic access.
dataTestId Testing hook ID.
enableAsHotspot Enables guided tour hotspot.
guidedTourHotSpotTitle Guided tour hotspot title (localized).
guidedTourHotSpotDescription Guided tour hotspot description (localized).

Structure

  • The calendar determines which month or period is shown first when it loads, ensuring users start with a relevant view.
  • It defines how users can interact with dates, whether by selecting a single day or a range of days.
  • The component manages zoom levels, allowing navigation between detailed daily views, monthly overviews, or broader yearly perspectives.

(Configured in General Properties)

  • displayName - Sets the display name of the component shown in the structure panel. For example, "Meeting Calendar" allows for easy identification of the calendar's purpose in the component structure.

(Configured in Visual Properties)

  • selectionMode — Sets how users can interact with the calendar with options "date" (select a single date) or "timeframe" (select a range of dates). For instance, using "timeframe" mode allows users to select vacation periods or reporting periods spanning multiple days.

Single Select in comparison to Date Range Picker visualized

(Configured in Visibility)

  • displayConditions — Defines conditions for displaying the component. Allows the calendar to be shown or hidden based on dynamic conditions like user role or application state.

Styling

(Configured in Visual Properties)

  • viewDate — Determines which month is initially displayed when the calendar loads. Options include currentMonth, previousMonth, or nextMonth.
  • minZoomMode — Sets the minimum zoom level (most detailed view) users can navigate to.
  • maxZoomMode — Sets the maximum zoom level (least detailed view) users can navigate to.

Visual Properties tab with options displayed

Actions & Variants

Actions

(Configured in Events)

  • events — Configures the events that the component can trigger and respond to.
  • ON_CALENDAR_DATETIME_CHANGE — Triggered when a user selects a date or date range. Provides the selected date (in date mode) or from/to dates (in timeframe mode) in the event payload.
  • ON_INIT — Triggered when the component is initialized. Can be used to perform setup operations.
  • ON_DESTROY — Triggered when the component is removed from the DOM. Useful for cleanup operations.

Datasource

(Configured in Datasource)

  • fetchEntityCollectionDataSourceId — Specifies the data source ID for retrieving calendar indicator data. Example: api/calendar-events connects to an endpoint that provides date indicators.
  • getEntityCollectionHttpRequestParametersMap — Configures HTTP parameters for fetching calendar indicator data. Maps additional request parameters for dynamic filtering based on context.

Authorization

(Configured in Authorization)

  • visibilityPolicySetId — Determines the visibility of the component based on specified policy sets. For example, setting to adminOnlyPolicy restricts the calendar to users with admin privileges.

Tests

(Configured in Testing Hooks)

  • id — Unique identifier for programmatic access. Example: mainCalendar.
  • dataTestId — Testing hook ID for automated tests. Example: date-selector-calendar.
  • enableAsHotspot — Enables the calendar as a guided tour hotspot.
  • guidedTourHotSpotTitle — Localized title for the hotspot.
  • guidedTourHotSpotDescription — Localized description for the hotspot.

(Configured in Visual Properties)

  • useMockData — Determines whether sample indicator data is used for demonstration. When enabled, predefined color indicators appear without a real data source (useful for demos and automated tests).
  • Figma link: tba
  • Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id3/9-date-picker/calendar

Guidelines

Usage

  • Use when users need to pick one date or a contiguous date range. Choose the interaction via selectionMode: "date" (single) or "timeframe" (range).
  • Start users in the relevant period with viewDate and constrain navigation with minZoomMode / maxZoomMode.
  • Expose stable hooks for tests and analytics via id and dataTestId.

Interactions & Events

React to user selection by handling ON_CALENDAR_DATETIME_CHANGE to update related UI or trigger logic.

Visibility & Authorization

  • Show or hide the calendar based on runtime context using displayConditions.
  • Gate access with visibilityPolicySetId when role-based visibility is needed.

Dos & Don’ts

Do Don’t Article setting(s)
Set selectionMode: "timeframe" when ranges are required so users can drag/select a span. Simulate ranges in "date" mode (it emits only a single date). selectionMode, events.ON_CALENDAR_DATETIME_CHANGE
Constrain zoom with minZoomMode/maxZoomMode to the levels your use case needs. Allow unrestricted zooming that sends users into irrelevant levels. minZoomMode, maxZoomMode
Initialize the first visible month with viewDate to match the task (e.g., next month for planning). Rely on defaults that open on an unhelpful month. viewDate
Populate indicators through a data source and pass scoped filters. Hard-code indicator dots or mix mock and real data in production. fetchEntityCollectionDataSourceId, getEntityCollectionHttpRequestParametersMap, useMockData
Treat ON_CALENDAR_DATETIME_CHANGE as the place to react to user selection. Poll the component for selection state. events.ON_CALENDAR_DATETIME_CHANGE
Use the guided-tour hotspot with brief, localized text as optional help. Place essential instructions only in the hotspot/tooltip-style copy. enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription

Accessibility

  • Provide concise, localized helper text via guidedTourHotSpotTitle / guidedTourHotSpotDescription when enableAsHotspot is used.
  • Reduce cognitive load by starting in-context with viewDate and keeping navigation bounded with minZoomMode / maxZoomMode.
  • Ensure deterministic automation and auditability with dataTestId and id.
  • Avoid color-only meaning by pairing indicator visuals with reactions to ON_CALENDAR_DATETIME_CHANGE (e.g., updating nearby text).
  • Use displayConditions to prevent rendering when irrelevant, reducing tab stops and screen-reader noise.
  • No labels