This guideline now covers both SAPUI5 and SAP Web Components. Learn more.
Information
Icon
false

Intro

The calendar is a UI component used to select a single date, multiple days, or a date range. It displays time-related data such as year, month, and date, and supports navigation between months and years, including multi-month views.

Calendar showing November 2025 with day 4 as the current date.

Calendar

Component availability

This component is available in the following libraries:

<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.ui.unified.Calendar">sap.ui.unified.Calendar</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FCalendar%2F">ui5-calendar</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fdesign%2FSILcWzK5uFghKun9jx6D7c%2FSAP-Web-UI-Kit%3Fnode-id%3D521-6837">Calendar</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>
<div> <div data-valign="middle">Library</div> <div data-valign="middle">Technical Name</div> <div data-valign="middle">Identifier</div> </div> <div> <div data-valign="middle">SAPUI5 Demo Kit</div> <div><a href="https%3A%2F%2Fui5.sap.com%2F%23%2Fentity%2Fsap.ui.unified.Calendar">sap.ui.unified.Calendar</a></div> <div data-valign="middle">:badge, info, large, _, SAPUI5:</div> </div> <div> <div data-valign="middle">SAP Web Components</div> <div data-valign="middle"><a href="https%3A%2F%2Fui5.github.io%2Fwebcomponents%2Fcomponents%2FCalendar%2F">ui5-calendar</a></div> <div data-valign="middle">:badge, info, large, _, SAP Web Components:</div> </div> <div> <div data-valign="middle">SAP Fiori for Web UI Kit (Figma)</div> <div data-valign="middle"><a href="https%3A%2F%2Fwww.figma.com%2Fcommunity%2Ffile%2F1494295794601744471">Calendar</a></div> <div data-valign="middle">:badge, info, large, _, Figma:</div> </div>

When to Use

2
do
false

Use the calendar to:

  • Let users select a single date, multiple days, entire week, or a date range.
  • Display multiple months at once.
  • Provide a date selection control that is always visible and prominent.
  • Help users view the year, month, week, and date together when making a selection, for example when choosing a date based on the day of the week.
  • Allow users to select dates visually and avoid ambiguity caused by locale-specific date formats, such as day-month-year or month-day-year.
  • Highlight special days or hide and disable specific dates.
dont
false

Don’t use the calendar to:

  • Allow entering large amounts of data. Use the date picker instead.
  • Handle scenarios where the keyboard is the primary input method. Use the date picker instead.
  • Display a permanently visible calendar when screen space is limited.
  • Support scenarios where selecting a date range is the user’s primary task. Use date range selection instead.
  • Display a range of weekdays in a single row. Use the calendar date interval instead.
  • Compare calendars from multiple people. Use the planning calendar instead.
  • Select combined date and time values. Use the date/time picker instead.
toptip
  • Use mixed calendar views only when users need to work across different calendar systems.
  • Set minimum and maximum dates to restrict selection and prevent invalid or irrelevant choices.
  • Support the selection of weeks by calendar week numbers for week-based planning.
  • Show calendar week numbers only when users benefit from weekly planning.
  • Mark non-working days as consistent blocks and position them adjacent to weekends.
  • Highlight irregular holidays or events as special days and explain them using a legend.
  • Support multiple-month view when selection across two months is likely (for example, planning a vacation).
  • Provide a “Today” icon button to let users quickly navigate back to the current date.

Anatomy

The calendar supports date, month, and year view and consists of the following elements:

  1. Previous month button: Moves calendar view back to previous month.
  2. Month view button: Opens the view for selecting a specific month.
  3. Year view button: Opens the view for selecting a specific year.
  4. Next month button: Moves calendar view to next month.
  5. Days of the week: Displays the names of the weekdays (for example, Mon, Tue, Wed, Thu, Fri, Sat, Sun).
  6. Today: Indicates the current day on the calendar.
  7. Non-working day: Marks weekends or other non-working days.
  8. Days from next month: Displays days from adjacent months for easier navigation.
  9. Selected day: Highlights the day currently chosen by the user.
  10. Working day: Regular weekday displayed in the calendar grid.
  11. Calendar weeks (optional): Displays week numbers.

Calendar anatomy with numbered pointers 1–11 identifying navigation buttons (months, years), days of the week, today, non-working days, selected day, and calendar weeks.

Calendar anatomy

Month view

  1. Previous year button
  2. Year view button
  3. Next year button
  4. Selected month button

Year view calendar showing 12 months, with navigation controls for the previous and next year and the selected year.

Month view calendar anatomy

Year view

  1. Previous year range button
  2. Year range button
  3. Next year range button
  4. Selected year button

Year view calendar showing 20 years (2015–2034), with navigation controls for the previous and next 20-year range and the selected year.

Year view calendar anatomy

Types

There are three calendar types based on the selection behavior:

A. Single-day selection
B. Multiple-day selection
C. Range selection

Three calendars showing single-day selection, multiple-day selection, and date range selection.

Single day, multiple day, and range selection calendar types

There are also types based on the level of granularity users can select:

A. Month view
B. Year view
C. Year range view

Three calendars showing month view (12 months, Jan–Dec), year view (20 years, 2015–2034), and year range view (8 ranges of 20 years each).

Month view, year view, and year range view

Mixed calendar

Displays two calendar systems together, allowing users to view and select dates across both systems on one calendar. Each day cell shows the corresponding dates from both calendars.

Mixed calendar showing two combined calendar systems in a day view.

Mixed calendar

Multiple months view :badge, info, large, _, SAPUI5 Only:

Displays two months vertically one under another, allowing users to select dates across month boundaries. It supports single day, multiple day, week, or date range selection.

Note: This view supports displaying multiple months. However, we recommend showing two.

Two-month calendar view in vertical orientation showing November and December 2025.

Multiple months view - vertical orientation

States

The calendar component supports states that indicate interaction and status. Each state communicates the current status and supports navigation.

Component states

The dates in the calendar support two states: enabled and disabled.

A. Enabled state: Displays an interactive date.

B. Disabled state: Displays a non-interactive date.

Calendar component showing an enabled date (A) and a disabled date (B).

Calendar component states

For more information, see Component States.

Interaction states

The enabled date cells support two interaction states: regular and hover.

A. Regular: Displays the default state.

B. Hover: Displays the hover state when the cursor is over an enabled date cell.

Calendar showing regular state (A) and hover state (B), with the hover state highlighted.

Calendar interaction states

For more information, see Interaction States.

Focus state

The focus state indicates which element is focused.

A. Unfocused: Displays the default, unfocused state.

B. Focused: Displays a visible focus border around the date (for example: 25th), month, or year.

Calendar showing unfocused (A) and focused (B) date cells.

Calendar focus state

For more information, see Focus States.

Selection state

Selection state is applied after the user selects an element. The selected element is visually distinct from other elements.

A. Unselected: Displays the default, unselected state.

B. Selected: Displays the selected state, visually distinct from unselected elements.

Calendar showing unselected (A) and selected (B) date cells.

Calendar selection state

For more information, see Selection States.

Behavior and Interaction

The behavior and interaction of the calendar depends on the calendar type. Some interactions are only available for specific calendar types.

Selection

The calendar supports different types of selection:

Single-day selection

The user can select a single day. The selected day remains selected when navigating across months. Clicking the same day twice deselects it.

On touch devices, interaction is similar but without hover. Use a single-finger tap gesture. For more information, see Gestures.

Two-calendar sequence showing selection of a single day using a mouse.

Using mouse device to select a day in the calendar

Multiple-day selection

The user can select multiple non-consecutive days by clicking each day individually. Clicking the selected days again deselects them.

Two-calendar sequence showing selection of non-consecutive days using a mouse.

Using mouse device to select multiple days from the calendar

Selecting a date range

The user can select a date range by clicking on the first day and then the last day. All days in between are selected. The selected range is preserved while switching between months.

Two-calendar sequence showing selection of a date range using a mouse.

Using mouse device to select date range from the calendar

Selecting an entire week :badge, info, large, _, SAPUI5 Only:

If the calendar week number is displayed, users can select an entire week by clicking its week number. The selected week is preserved when switching between months, even if the week spans across two months.

Two-calendar sequence showing selection of an entire week by clicking the week number.

Selecting an entire week using mouse device

Month and year navigation flow

The user can navigate through months, years, and year range by clicking the previous/next calendar buttons and selecting the month, year, or year range controls.

Changing months with previous/next buttons

Clicking the navigation buttons moves to the previous or next month within the same year.

Two-calendar sequence (November and December 2025) showing navigation between months using previous and next buttons.

Navigating through different months using the previous/next buttons

Changing months in month view

When selecting the month at the top, the calendar switches to a month view, showing all months of the year. After selection, the calendar returns to the day view and displays the chosen month.

Two-calendar sequence showing selection of a month from the header in the first calendar, switching to month view with all 12 months, and highlighting November 2025 in the second calendar.

Changing months in month view

Changing years in year view

Clicking the year button at the top opens the year view of the calendar. After a year is chosen, the calendar returns to the day view and displays the selected year.

Two-calendar sequence showing selection of a month from the header in the first calendar, switching to month view with all 12 months, and highlighting November 2025 in the second calendar.

Changing years in year view

Changing year range

Selecting the year range button at the top opens the year range view of the calendar. After a range is chosen, the calendar returns to the year view and displays the selected year.

Two-calendar sequence showing selection of a year range (2015 - 2034) from the header in the first calendar, switching to year range view with multiple 20-year ranges, and highlighting 2015–2034 in the second calendar.

Changing year range in the year range view

Two-month calendar navigation – vertical

In the two-month view, the user can navigate through months via previous/next buttons. The months change with a step of one month. Example: October – November changes to November – December.

Two-calendar sequence showing vertical two-month view, navigating from October–November 2025 to November–December 2025 using the next button.

Navigating through different pair of months using the previous/next buttons – vertical orientation

Tooltip

The calendar supports tooltips for:

For detailed guidance on interaction patterns and tooltip behavior, refer to the Tooltip.

Two-calendar sequence showing tooltips on navigation buttons, month and year controls, today, special days, and non-working days.

Calendar tooltips

Responsiveness

Use the calendar within a responsive layout container. The calendar itself is not responsive.

The calendar is optimized for both cozy and compact content densities.

For more information, see Content Density (Cozy and Compact).

Two calendars showing compact mode (A) and cozy mode (B), with reduced spacing in compact mode and larger spacing in cozy mode.

Calendar in compact and cozy mode

Multiple-month view switches to one-month view in cozy mode

When using the multi-month view, the calendar adjusts based on screen size. On small screens, only a one-month calendar is displayed.

Two calendars showing compact mode (A) and cozy mode (B), with reduced spacing in compact mode and larger spacing in cozy mode.

Responsiveness from two-month view to a single-month view on mobile device

Accessibility

SAP follows international standards, such as WCAG and WAI-ARIA, and strives to make our business solutions accessible and inclusive.

For more information, see Accessibility in SAP Fiori and the Accessibility Design Tools Handbook.

Keyboard navigation

The following keyboard combinations are supported by the SAPUI5 calendar component.

<div> <div>Key Combination</div> <div>What it Does</div> </div> <div> <div><strong>Space or Enter</strong></div> <div> <p>If the focus is on a day/month/year, selects it. On second press of SPACE/Enter deselects the day.</p> <p>If the focus is on the month/year button, opens the corresponding view.</p> <p>If focus is on a month, selects this month. If focus is on a year, selects this year.</p> </div> </div> <div> <div> <p><strong>Shift + Page Up</strong></p> <p><strong>Alt + Page Up</strong></p> </div> <div>Moves the focus to the same day in the previous year.</div> </div> <div> <div> <p><strong>Shift + Page Down</strong></p> <p><strong>Alt + Page Down</strong></p> </div> <div>Moves the focus to the same day in the next year.</div> </div> <div> <div><strong>Ctrl + Shift + Page Up</strong></div> <div>Navigates ten years backward.</div> </div> <div> <div><strong>Ctrl + Shift + Page Down</strong></div> <div>Navigates ten years forward.</div> </div> <div> <div> <p><strong>Home</strong></p> <p><strong>End</strong></p> </div> <div>Navigates to the first or last day of the week. If the month view is open, navigates to the first or last month of the current row. If the year view is open, navigates to the first or last year of the current row.</div> </div> <div> <div> <p><strong>Ctrl + Home</strong></p> <p><strong>Ctrl + End</strong></p> </div> <div>Navigates to the first or last day of the month. If the month view is open, navigates to the first or last month of the current year. If the year view is open, navigates to the first or last year of the current year range.</div> </div> <div> <div>Interval Selection</div> <div></div> </div> <div> <div><strong>Ctrl + Space</strong></div> <div>Selects and deselects the currently focused date.</div> </div> <div> <div>Month View Navigation</div> <div></div> </div> <div> <div> <p><strong>Page Up</strong></p> <p><strong>Page Down</strong></p> </div> <div> <p>If the month view is open, navigates to the same month of the previous or next year.</p> <p>If the year view is open, navigates to the previous or next year range.</p> </div> </div> <div> <div>Year View Navigation</div> <div></div> </div> <div> <div><strong>F6</strong></div> <div>Moves the focus to the first element in the tab chain of the next F6-group.</div> </div> <div> <div><strong>Shift + F6</strong></div> <div>Backwards navigation.</div> </div> <div> <div> <p><strong>Alt + Down Arrow</strong></p> <p><strong>Alt + Up Arrow</strong></p> </div> <div>Moves it to the first element in the tab chain of the next or previous F6-group.</div> </div>

Screen reader support

For details on screen reader support and Accessible Rich Internet Applications (ARIA), see the UI5 Screen Reader Support and WAI-ARIA Authoring.

Content

Mixed calendar

The mixed calendar view supports a combination of two different calendars into one calendar view. The number of weeks is not available for this type of calendar.

Three calendars showing a mixed calendar in day view (A), month view (B), and year view (C).

Mixed calendar in day view (A), month view (B) and year view (C).

Legend

The legend explains days with special markings and colors used in the calendar. It includes 20 placeholders for custom colors and a set of standard colors:

A. Standard: Legend items such as today, selected, working day, and non-working day.

B. Special: Legend items such as appointments or other irregular events. The appointment section includes color values for different appointment types, which must be configured in the app.

The legend can appear next to the calendar or be accessed via a Special Days button.

Calendar legend showing standard items and 10 custom-colored special days.

Calendar legend showing 4 standard and 10 custom-colored items

Localization

The calendar supports left-to-right (LTR) and right-to-left (RTL) reading directions. All features are supported in both directions.

Calendar showing left-to-right (LTR) layout with days ordered Monday to Sunday.

Left-to-right calendar

Calendar showing right-to-left (RTL) layout with days ordered Sunday to Monday and mirrored navigation.

Right-to-left calendar

Features

Supported calendars

The calendar supports five calendar types – Gregorian (default), Islamic, Japanese (A), Persian (B), and Buddhist (C).

Three calendars showing Japanese calendar (A), Persian calendar (B), and Buddhist calendar (C).

Examples of Japanese, Persian, and Buddhist calendars

Setting calendar weeks

The calendar lets you configure the first day of the week and the first week of the year by selecting a calendar convention. Available conventions include Default, which is based on the active format locale, ISO 8601 (A), Middle Eastern (B), and Western Traditional (C).

Three calendars showing default (A), Middle Eastern (B), and Western traditional (C) week configurations.

Calendars using the ISO 8601, Middle Eastern, or Western Traditional convention

Showing/Hiding calendar week numbers

The calendar can display or hide the week numbers based on the configuration settings. This feature is typically used in views where planning by week is relevant.

Two calendars showing week numbers enabled and hidden.

Calendar examples with and without week numbers

Pre-selected date or range

It is possible to define a pre-selected date or a specific date range that appears automatically when the user first opens the calendar. New selections will clear the pre-selected dates.

Two calendars showing a pre-selected date and a pre-selected date range.

Calendar with a pre-selected date or date range

Adjusting calendar width :badge, info, large, _, SAPUI5 Only:

The calendar is not responsive, but you can adjust its width depending on the use case. This helps maintain visual balance, readability, and alignment with surrounding UI elements.

Two calendars showing different widths: wider and reduced.

Calendar with modified width

Start/End of the week :badge, info, large, _, SAPUI5 Only:

Each weekday can be set as the first day of the week in the calendar (for example, Tuesday, Wednesday, or any other day). Changing the start of the week affects the visual order of weekdays, week boundaries, and related calculations such as week numbers, helping users interpret dates more intuitively within their local or business context.

Calendar showing weekday order starting with Tuesday.

Calendar showing Tuesday as a first day of the week

Restricted date range

The calendar can be configured with a minimum and a maximum date that restrict the range of selectable days. Dates outside the defined range are visually disabled and cannot be chosen.

Note: The today’s date can be focusable even if it is not in the defined range.

Calendar showing disabled dates outside a defined selectable range.

Calendar with restricted date range

Disabled dates

The calendar dates can be disabled (for example, 11th, 12th, 13th, and 25th). Unlike the restricted date range, those dates can be random and non-consecutive. The disabled dates can’t be selected and are not focusable.

Calendar showing specific dates disabled and unavailable for selection.

Calendar with disabled dates

Non-working days

The calendar allows the definition of non-working days. They should follow a consistent pattern and be adjacent to the weekend days.

Note: If you need to mark random days, highlight them as special days with legend.

Calendar showing non-working days highlighted and unavailable for selection.

Calendar with marked non-working days

Custom initial focus date :badge, info, large, _, SAPUI5 Only:

By default, the calendar displays the current day without a focus. You can configure it to apply focus to a predefined date, guiding the user’s attention. For example, in a booking flow, focus can be set to the first available date, helping users immediately see and select a valid option.

Calendar showing a pre-focused date highlighted.

Calendar with pre-focused date

Current date :badge, info, large, _, SAPUI5 Only:

The current date can be enabled as a quick navigation through the “Today” button, which jumps the calendar to the current date. When used in month, year or year-range picker view, the calendar navigates to the default date picker view and highlights today.

Calendar showing a Today button for quick navigation to the current date.

Calendar with “Today” button

Framework Comparison

Some behaviors differ between frameworks due to implementation specifics. The table below summarizes the differences between SAPUI5 and SAP Web Components and lists the framework-specific patterns.

<div> <div>Feature</div> <div>SAPUI5</div> <div>SAP Web Components</div> </div> <div> <div>The calendar can display two months in vertical alignment. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#multiple-months-view-badge-info-large-_-sapui5-only">Multiple months view</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The user can select the whole week by clicking on the week number. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#selecting-an-entire-week-badge-info-large-_-sapui5-only">Selecting an entire week</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The calendar width can be adjusted depending on the use case. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#adjusting-calendar-width-badge-info-large-_-sapui5-only">Adjusting calendar width</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>Each weekday can be set as the first day of the week in the calendar. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#startend-of-the-week-badge-info-large-_-sapui5-only">Start/End of the week</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The initial focus date can be customized to any target date. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#custom-initial-focus-date-badge-info-large-_-sapui5-only">Custom initial focus date</a> section.</div> <div>Available</div> <div>Not available</div> </div> <div> <div>The “Today” button can be enabled as a quick navigation component. For more information, see the <a href="https://www.sap.com/design-system/fiori-design-web/ui-elements/calendar#current-date-badge-info-large-_-sapui5-only">Current date</a> section.</div> <div>Available</div> <div>Not available</div> </div>

[internal_only] To request one of these features for SAP Web Components, submit an InnerSource request.[/internal_only]

Guidelines

Components

Date/Time Picker
Date Range Selection
Calendar Date Interval
Planning Calendar
Gestures

Implementation

SAPUI5

Calendar (samples)
Calendar (API reference)

SAP Web Components
Calendar
Calendar Legend

Specifications

Calendar - Legend
(visual design)
Two-Month Calendar
(visual design)

SAP Web UI Kit

Calendar

Guidelines

Components

Date/Time Picker
Date Range Selection
Calendar Date Interval
Planning Calendar
Gestures

Implementation

SAPUI5

Calendar (samples)
Calendar (API reference)

SAP Web Components
Calendar
Calendar Legend

UI Kit (Figma)

SAP Fiori for Web UI Kit / Calendar