Intro

The calendar control lets users select a single date, multiple days, entire week(s), or a date range. The calendar shows all time-related data (year, month, week, day, date) at a glance. It also allows users to navigate directly from one month or year to another, or to display multiple months.

Calendar component

When to Use

Use the calendar if:

You want the user to select a single date, multiple days, entire week(s), or a date range.
You want to display multiple months at once.
The calendar always needs to be visible and prominent.
Users need to see the year, month, week, weekday and date at a glance to decide which date to select. For example, a user might want to select a date based on the day of the week.
Users might be used to different locale-specific date formats (such as day-month-year or month-day-year). Enabling them to select the date visually using the calendar bypasses format-specific interpretation.
You want to highlight special days or hide/disable specific days.

Don't

Don’t use the calendar if:

The user is a power user who has to enter a lot of data fast. In this case, use the date picker.
The keyboard is the primary input device. In this case, use the date picker.
The available screen space is limited and displaying the calendar permanently would take up too much space.
The user’s primary goal is to select a date range. In this case, use date range selection.
You want to display a range of weekdays in a single row. In this case, use the calendar date interval.
The user wants to compare calendars from different people. In this case, use the planning calendar.
The user wants to select combined date and time values. In this case, use the date/time picker.

information

The calendar can stand alone as a control, but is also part of many other controls, such as the date picker, date/time picker, or the date range selector.

Anatomy

Calendar anatomy

Previous button: Moves calendar view back to previous month.
Month view button: Opens the view for selecting a specific month.
Year view button: Opens the view for selecting a specific year.
Next button: Moves calendar view to next month.
Days of the week: Displays the names of the weekdays (for example, Mon, Tue, Wed).
Today: Indicates the current day on the calendar.

Non-working day: Marks weekends or other on-working days.
Days from next month: Displays days from adjacent months for easier navigation.
Selected day: Highlights the day currently chosen by the user.
Working day: Regular weekday displayed in the calendar grid.
Calendar weeks: Shows the week numbers (Gregorian calendar only); can be hidden if not needed.

Types

The following calendar types are available:

Single Day Selection

The user can select a single day at a time.

Single day selection

Range Selection

Lets users choose a continuous block of dates, such as an interval or a full week.

Range selection

Multiple Day Selection

Lets users select multiple non-consecutive days, entire weeks or a custom date range.

Multiple day selection

Multiple Months

Displays two or three months side by side, allowing users to select dates across month boundaries. It supports single-day, multiple-day, week, or date range selection.

Multiple month view

Month and Year View

The control offers a day view, month view, year view, or year ranges.

Month, year, and year range calendar views

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 Gregorian and Islamic calendar

Behavior and Interaction

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

By default, the focus starts on the current day, but can be customized to fit the use case.

Selecting a Single Date

Clicking the date selects it. Clicking the date again deselects it.

Single day selection

Selecting a Date Range

The user selects a date range by clicking the first and last day of the time period, which also selects all the days in between. Alternatively, the user can select two different dates and press Shift+Enter twice.

Date range selection

Selecting an Entire Week

To select an entire week, the user clicks the number for calendar week (if displayed). Alternatively, the user can select one day within the week and press Shift+Space simultaneously.

Selection of an entire week by clicking on the calendar week

Selecting Multiple Days

Multiple days are selected by clicking the desired days individually. Clicking the selected days again deselects them.

Selection of multiple days

Changing Months

If the current month is selected, the view changes to the month view and the user can change the month. By clicking a month, the user changes the month and the view changes back to the day view.

Changing the month using the month view

Clicking the arrow in the day view of the calendar shows the next month of the same year.

Changing the month using the arrow

Changing Years

Clicking the current year changes the view to year view. When the user selects a year, the view changes back to the day view.

Changing the year using the year view

Clicking the arrow in the month view shows the same selected month in the next year.

Changing the year using the arrow

Clicking the year range changes the view to year range view. When the user selects a year range, the view changes back to the year view.

Changing the year using year range view

Clicking the arrow in the year view shows the next year range, changing in increments of 20 years.

Changing the year range in year view

Clicking the arrow in the year range switches to the next 180 year span.

Switching the year span

Responsiveness

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

When using the multiple month view, the calendar adapts to the size of the screen. On small screens, only one calendar is displayed.

Properties

Customization

The control allows you to show or hide the calendar weeks. You can also customize the calendar by defining the start and end of a week, or by defining the earliest or latest date.

Specific days can also be disabled, for example non-working days or public holidays.

Calendar without calendar weeks and with a few disabled days (grayed out)

Legend for Highlighted Days

Within the calendar, special days can be highlighted. A legend is used to define the meaning of the highlights. Application development teams are responsible for using the colors consistently within one product area.

Calendar with highlighted days and legend

Localization

The calendar adapts to both left-to-right (LTR) and right-to-left (RTL) languages. In RTL setups, the layout is mirrored to match the natural reading direction.