Intro

The planning calendar lets users view and create appointments. They can display appointments for multiple objects, as in a team calendar, and compare them.

A digital calendar interface displays multiple team members and their scheduled events for August 24, 2026. Rows show individuals such as John Miller, Michael Adams, Donna Moore, and Emily Carter with color-coded appointments. Events include workshops in Room 105 and Room 109, a customer meeting, product demo, sync sessions, and release milestones labeled Release 2608. The layout uses a modern design with a horizontal time scale from 8 to 19 hours and options for selecting all entries, creating events, and changing the view.

Planning calendar

When to Use

2
do
false

Use the planning calendar to:

  • Compare objects of the same type over a period of time.
  • Show fewer than 100 lines.
dont
false

Don’t use the planning calendar to:

  • Show a calendar for one object with a detailed overview of appointments over a long time interval.
  • Show a complex or graphical representation. Use a Gantt chart instead.
  • Show more than 100 lines. Use the Gantt chart instead.

Anatomy

The planning calendar consists of the following components:

A digital calendar interface displays weekly schedules for multiple team members. The view spans August 24, 2026 to September 6, 2026, showing weeks 35 and 36 with daily columns. Colored appointments indicate events such as workshops in Room 109 with customers, weekly reviews, and various task codes. Profile photos and names of team members appear on the left, while navigation controls and view options are visible at the top.

Anatomy of the planning calendar

1. Header: Contains the toolbar and the navigation.
2. Toolbar: Consists of the calendar title (optional) and the toolbar actions (app-specific actions, view switch, and legend).
3. Navigation: Contains back and forward arrows, the Today  button, a date interval link, and the date strip.
4. Time strip: The time strip reflects the selected view, and shows the hours, days, or months currently visible.
5. Calendar weeks: In all views that show days (Days, 1 Week, 1 Month, Months), you can display calendar weeks in a separate line below the time strip (property: showWeekNumbers).
6. List item: The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and non-working days.
7. Row header: The row header identifies the object for which the appointments are shown.
8. Row: The row contains all appointments for an object. By default, alternating row coloring is enabled.

Toolbar

The calendar toolbar is based on the responsive overflow toolbar. All elements are optional.

The view switch can be a segmented button (four views or less) or a select component (five views or more). Always place actions that affect the entire calendar in the toolbar.

You can also add a multi-select toggle to the toolbar. For example, this could be used to select multiple people and delete them from the planning calendar.

A: Title
B: App-specific and generic actions
C: Legend
D: View switch

Shows a calendar toolbar labeled My Calendar. The toolbar includes a search field, a Create button, a Legend Icon-Button and a View Selection set to Hours.

Toolbar structure

Legend

To show the types for days and appointments, the planning calendar uses a specific legend component (sap.m.PlanningCalendarLegend).

Users open the legend using a standard legend button in the toolbar (:icon-legend). Like all other actions in the toolbar, you must add the legend button explicitly.

The planning calendar legend has two non-collapsible sections containing legend elements. By default, these are called Calendar and Appointments, but you can change the titles. If no elements are available for a section, it isn't displayed.

hint
Load the sap.ui.unified library to prevent delays.

A. Popover title: You decide which container to use. We recommend a popover to keep the context, but a dialog or dynamic side content are also valid options.

B. Calendar section: The calendar section contains four standard legend items: Today, Selected, Working Day, and Non-Working Day. You can turn off unused items via the standardItems property. Ensure the Selected element is in the legend when the calendar is in 1-month mode at smartphone size. The component doesn't add this automatically.

C. Special days: You can define special days that are highlighted in the date strip. Add the special day colors to the legend manually, as this isn't done automatically.

D. Appointments section: The Appointments section contains the color values for available appointment types. You must explicitly define which color represents which type.

E: Combined appointments: If combined appointments in the calendar are of the same type (in  Months  view), they take the color of that type. Combined appointments of different types are marked gray. We also recommend adding the gray color for mixed combined appointments to the  Appointments  section in the legend.

Popover displaying a legend for the planning calendar. The calendar section includes items labeled Today, Selected, Working Day, Non-Working Day, Office, and Homeoffice with colored icons. The appointments section lists Weekly Meetings, Design Reviews, Customer Meeting, Team Meeting, Onboarding, Release, and Combined Appointments, each with distinct color dots.

Legend

guideline
Ensure colors are used consistently within your product area.

View Switch

The view switch lets users switch between different time intervals (calendar views). Depending on the number of available calendar views, the view switch can be a segmented button (four views or less) or a select component (five views or more). The select component has a visible label to fulfill accessibility requirements.

The default calendar views are Hours, Days, Months, 1 Week, and 1 Month. You can choose which views to include, depending on the use case, and how many values each view displays. You can change the default number of values shown, but should ensure the app remains responsive. You can also create custom views.

1 Month View

The 1 Month view shows an entire month. On desktop devices, it always displays an interval of 31 days. When the displayed month is shorter (28, 29, or 30 days), days from the following month are displayed. These days have a different visual state and serve as navigation to the following month.

The 1 Month view has an additional style for half-column appointment distribution, which is mainly used to avoid overlapping. The property appointmentRoundWidth can be set to "HalfColumn" or "None" (default). Currently, the appointment width is always rounded to 12 hours. Note: This property is also applied when the calendar interval type is Days and the view shows more than 20 days.

On size M and size S, the 1 Month view is adaptive. It consists of a calendar and a list of appointments for the selected day.

If you offer the 1 Week view, we strongly recommend displaying a different number of days in the Days view (more or less than seven). Otherwise, users might get confused, as navigation differs between the two views.

Relative View

When you need to display a period that isn't connected to a specific time or date, you can map the calendar to relative dates (instead of absolute calendar dates like "Week 1" and "Week 2"). For example, you might use this to divide the year into quarters.

You specify the names of the intervals in the time strip and the index picker, as well as the interval size. The index picker then determines how many days are in one interval. This is configured in the PlanningCalendarView by setting the relative property to "true".

In addition, you set a minimum date (property: minDate) in the planning calendar to determine the start date of the relative views.

Row Header

The row header identifies the object for which the appointments are shown. It pops in if there isn't enough space. You can also add an action on the row header (event: rowHeaderClick).

A. Picture or icon 

B. Title
C. Subtitle

Shows a row header featuring a circular avatar photo on the left and text details on the right with title and byline.

Row header

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. This lets you show the calendar for one object.

Note: The component was designed mainly to compare time slots of different objects. For this reason, the time axis is shown horizontally and, depending on the interval, the appointments might shrink. In this case, the text is cut off rather than truncated.

Non-Working Days

If the users have a specific working schedule, the non-working days can be different on each row. This can be applied not only for weekends, but also for non-working days based on specific schedule differences.

Appointments

Structure

Appointments consist of an icon or picture, a title, and a subtitle. Concurrent appointments are shown one above the other.

The app can set up to 20 types of appointments. Each type has its assigned color. Always choose appointment types with contrasting colors. Make sure that each type is also represented as a text, and not only by the color.

Setting an appointment to tentative turns the outline into a dotted stroke.

A: Color indicator
B: Icon or image
C: Title
D: Subtitle
E: Description

Appointment with a color indicator on the left, an icon followed by a title, subtitle and description.

Appointment structure

Sizes

There are four size-types for appointments:

A. Half-size: Always displayed in one row, shows the title.
B. Regular: Displayed in two rows. One-row display is also possible if the appointmentsReducedHeight property is set to “true”.
C. Large: Always displayed in three rows, also shows the description for each appointment (if available).
D. Automatic: The number of rows is determined automatically.

Shows 3 appointments in different sizes. First a half-sized appointment with only one line. Then a regular appointment with two lines of text and last a large appointment with 3 lines of text.

Appointment sizes

Appointment Size
Content
Rows
Half-Size
Title only
1 row
Regular
Title + subtitle
or
Title + description
2 rows
Large
Title + subtitle + description
3 rows
Auto
Automatically determined
Automatically determined

Combined Appointment

In the Months view, appointments within the same calendar week are combined to save space. The combined appointment shows the number of appointments in the same week. If an appointment takes place between two calendar weeks (for example, from Sunday to Monday), it isn't included in the combined appointments for either calendar week.

You can display a list of the appointments within a combined appointment in a popover, but you must implement this yourself. The component only provides the click event.

If necessary, you can disable combined appointments (property: GroupAppointmentsMode, value: “Expanded”).

Interval Appointment

Each row can also have interval appointments, which look different from half-sized appointments and always appear at the top of the row. Use interval appointments to show appointments that span a longer period, such as vacations or workshops. You can hide the space reserved for interval appointments if none exist for that period.

style
no-footprint

Behavior and Interaction

Calendar Navigation

Users can open a date picker to select the start time for the visible interval. What the picker shows initially depends on the view. The current day is marked.

The arrows let users navigate to the next or previous interval. Users can select the Today button to go back to the current date and time.

First Day Of The Week

You can set which day appears as the first day of the week. If you don't set a value, the component uses the locale default.

Multi-Select Mode

The component supports multi-select mode for list items. This allows users to delete multiple objects from the view, for example. Decide whether to show the planning calendar with or without multi-select mode, or whether to let users switch between the two modes.

Snapping Header

The planning calendar header area can stay fixed at the top of the screen (property: stickyHeader). This lets users scroll through calendars with many rows without losing context.

A digital calendar interface displays multiple team members and their scheduled events over several days. The view shows a timeline from August 24, 2026 to September 6, 2026, organized into Week 35 and Week 36. Color-coded blocks represent workshops, weekly reviews, and other appointments, with details such as room numbers and customer meetings. Profile photos and names appear on the left, while the main calendar grid occupies the center of the screen. The view is scrolled down and the snapped header is shown at the top.

Header snaps to the top when scrolling down

Switching the Row Header

To let users rearrange the planning calendar by switching the row header, you can implement a flexible row header. The component doesn't handle this automatically. Your team must implement it.

The list items in the row header can be a value of any appointment attribute. Appointment attributes are app-specific, so define them for your app. The component doesn't provide default attributes.

We recommend using the select component in place of the calendar title. The select component contains all the attributes that can serve as the row header. When users select a different attribute, the calendar is rearranged accordingly. You can also add a counter after the list items to indicate how many appointments fall into a specific group.

You can also use both the calendar title and the select component. In that case, place the title first, then the select.

On small screens, use the select component instead of the calendar title. If you want to keep the calendar title, place the select in the overflow menu.

Select Drop Down is open and a mouse hovers over selection of "Type"
Planning Calendar shows appointment types in the row headers like Workshop, Team Meeting and Product Demo

Drag and Drop

Drag and drop lets users move appointments (to enable drag and drop, use the property: enableAppointmentDragAndDrop). Moving an appointment automatically changes its start and end times (for example, if an appointment is scheduled from 1:00–2:00 PM, the user can drag it to change the time to 2:00–3:00 PM). When dragged, the appointment appears as a ghost element on the mouse cursor. A placeholder indicates the available drop target areas.

In the Hours view, users can move appointments to a specific time, with the placeholder snapping at every 30 minutes. In the Days view, users can move an appointment to a different day. The placeholder indicates the target day. When dropped, the appointment moves to that day but keeps its previous start and end hour. The Months view works the same way: the placeholder indicates the target month and, when dropped, the appointment moves to that month. The start and end hour and start and end day remain the same.

Users can move appointments between rows. Note that you may need additional coding to determine whether all users can perform this action.

Users can create appointments by clicking, dragging, and releasing on an empty space in the content area. Users can also change the duration of an appointment by clicking and dragging one side of the appointment. Both options are only available on desktop devices.

Combined appointments and interval appointments aren't draggable.

Drag and drop is only available on supported browsers.

warning
To comply with the WCAG 2.2 accessibility standard, the component must offer an alternative to the drag and drop feature. Provide direct access via keyboard shortcuts, which enables single pointer users to make use of virtual on-screen keyboards. Alternatively, use a popover for appointment information and a dialog for creating appointments. For an example, see Planning Calendar – With Appointments Modification.

Planning Calendar shows multiple team members and their scheduled events. The timeline is set to August 24, 2026 and displays hours across the top. Appointments include labels such as Release 2608, Workshop Room 105, Workshop Room 109 With Customer, Customer Meeting, Product Demo, Sync, Week, and Spotlight. A cursor is selecting one of the events, showcasing how drag and drop will look.

Drag and drop

Responsiveness

In size S, the component provides pop-in behavior, which allows the user to see as many appointments as possible and to connect them with the corresponding object. If the toolbar contains too many actions for the space available, the overflow icon appears.

The interval section displaying the hours, days, and months is responsive and shows 12 values in size L, 8 values in size M, and 6 values in size S. You can override this behavior, but you should then check that responsiveness still works.

A digital calendar interface in size L displays multiple team members and their scheduled events for August 24, 2026. Rows show individuals such as John Miller, Michael Adams, Donna Moore, and Emily Carter with color-coded appointments. Events include workshops in Room 105 and Room 109, a customer meeting, product demo, sync sessions, and release milestones labeled Release 2608. The layout uses a horizontal time scale from 8 to 19 hours and options for creating events, and changing the view.

Planning calendar - Size L

A digital calendar interface in size M displays multiple team members and their scheduled events for August 24, 2026. Rows show individuals such as John Miller, Michael Adams, Donna Moore, and Emily Carter with color-coded appointments. Events include workshops in Room 105 and Room 109, a customer meeting, product demo, sync sessions, and release milestones labeled Release 2608. The layout uses a horizontal time scale from 8 to 15 hours and options for creating events, and changing the view.

Planning calendar - Size M

A digital calendar interface in size S displays multiple team members and their scheduled events for August 24, 2026. Rows show individuals such as John Miller, Michael Adams, Donna Moore, and Emily Carter with color-coded appointments. Events include workshops in Room 105 and Room 109, a customer meeting, product demo, sync sessions, and release milestones labeled Release 2608. The layout uses a horizontal time scale from 8 to 13 hours and options for creating events, and changing the view.

Planning calendar - Size S

Resources

Guidelines

Implementation

Specification

Guidelines

Implementation