Table Personalization (Overview)

Table personalization can be used to modify the display and settings of a table.

It is a UI pattern that is used to change one or more of the following attributes:

Visibility of columns
Order of columns
Sorting
Grouping
Filtering

Table personalization can be applied to simple tables (up to about 20 columns) and complex tables (more than about 20 columns) using different controls.

Usage

Use the view settings dialog if:

The user is able to personalize fewer than about 20 columns.
A combination of sorting, filtering, and grouping is needed.

Use the table personalization dialog if:

The user is able to personalize fewer than about 20 columns.
Columns need to be shown/hidden and reordered.

Use the view settings dialog AND the table personalization dialog if:

The user wants to personalize fewer than about 20 columns.
A combination of show/hide and one other function is needed.

Use the P13n dialog if:

You are using an analytical table (ALV).
The user is able to personalize more than about 20 columns.
Complex queries have to be built for the respective table.

Do not use table personalization at all if:

The table has very few columns and rows.
A very complex filter is needed. In this case, consider using a filter bar instead of the filter tab.

Types

Simple Table Personalization

Table Personalization Dialog

All table personalization dialogs are opened via the Settings button on the right-hand side of the table toolbar.

The table personalization dialog can show/hide and reorder columns.

Hide/Show

To show or hide columns, the user only needs to select or deselect the checkboxes of the respective list item. Alternatively, the user can select all the items at once.

Reorder

Two buttons on the left-hand side enable a selected column to be moved up or down.

The user confirms the dialog to apply the options to the table.

For more information, see table personalization dialog.

Table personalization dialog

View Settings Dialog

The sort, filter, and group features can all be applied to a table simultaneously.

Sort

The first tab in the view settings dialog is the sort feature, which allows the table content to be sorted according to the chosen attribute.

The dialog offers two sort features:

The first group sorts the table by a general ascending or descending order.
The second group lets the user choose an attribute that fits either a column or part of a column since there are also columns that contain more than one data point.

Filter

The second tab in the view settings dialog is the filter feature, which can offer a single filter selection list or a category list. The category list provides an overview and guides the user to detailed filter selection lists via drilldown. The options available are single selection, multiselection, a category list, a predefined list, and a custom filter.

Group

The third tab in the view settings dialog is the group feature, which also offers two groups of attributes:

The first group offers a general ascending or descending order that controls the order in which the defined groups appear.
The second group offers attributes with which to group the corresponding data in the table.

View settings dialog – Sort tab

View settings dialog – Filter tab

View settings dialog – Group tab

Complex Table Personalization

P13n Dialog

The P13n dialog is the most complex personalization option for tables. It is used if none of the other options are sufficient. Like the view settings dialog, it can combine any of the tabs available. By allowing inclusion and exclusion filters, as well as several group options (for some tables only), it can form more complex queries than the other options.

Columns
The P13n dialog offers the most options for changing the table columns that are shown and the order in which they are displayed.

It can show/hide a column and alter the order of the columns.

Columns tab in the P13n dialog

Sort
It also allows the user to sort the table content according to the columns that are chosen and in a specific order.

For more complex sorting needs, the user can add the required number of criteria by clicking the button (Add New Line) at the end of the line.

P13n dialog – Sort tab

Filter
A filter option allows the user to filter the table information according to specific filter criteria, which can be included or excluded in the relevant section of the filter.

Each filter criterion consists of a column, an operator (depending on the data type of the column), and a value by which the selected column is filtered.

For more complex cases, the user can add filters by clicking the button (Add New Line), and remove them by clicking the button (Remove Line) at the end of each filter item.

P13n dialog – Filter tab

Group
The Group tab enables the user to group the table data by one or more columns.

For more complex grouping scenarios, the user can add more grouping options by clicking the button (Add New Line) at the right-hand side of each grouping line (only available for the ALV table).

P13n dialog – Group tab

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Table Overview (guidelines)
Table Personalization Dialog (guidelines)
P13n-Dialog (guidelines)
View Settings Dialog (guidelines)

Implementation

Table Personalization (SAPUI5 samples)
View Settings Dialog (SAPUI5 samples)
P13n-Dialog (SAPUI5 samples)
Table Personalization Dialog (SAPUI5 API reference)
Table Personalization Provider (SAPUI5 API reference)

Calendar Date Interval

The calendar date interval displays a range of days in a single row. The control allows the user to select a single day, multiple days, or a range of days. Content corresponding to the date selection is usually displayed below the control. The user can navigate the date intervals by browsing through them (using the previous and next arrows), or by going directly to a specific month or year.

Compared to the regular date range selection control, this control offers a flexible date range and consumes very little horizontal space.

Calendar date interval

The current day is highlighted by a colored frame. Weekends are shaded in a slightly darker gray.

Special day markup

You can mark special days, such as public holidays, with a colored line along the lower edge.

Alternative start date

You can configure the number of days displayed in a single interval (property: days) as well as the start date (property: startDate).

Responsiveness

The horizontal space occupied by the control is already minimal, so the responsiveness is limited to the width of the control.

Sizes M and L

On small screens, the maximum number of days per range interval is automatically reduced to eight.

Size S

Layout

The date interval control is divided into two main areas: date interval navigation, and date interval display and selection.

The navigation area contains two arrows (one to the left, one to the right), which allow the user to navigate easily to the previous and following date ranges. This area also contains month and year indicators, which display the currently selected month and year. These indicators also trigger the month and year navigation mode of the control.

The display and selection area is primarily used to display the range of days in the current date interval. You can also display a second row to show the calendar week can be shown (property: showWeekNumbers). When the user triggers month or year navigation, a range of months or years is displayed in this section to enable easy interval navigation.

Schematic visualization of calendar date interval

Behavior and Interaction

The behavior and interaction of the calendar date interval control can be divided into two parts: navigation and selection.

Navigation

Previous/Next

The user clicks the previous or next arrow to replace the currently displayed date interval with the previous or next date, respectively. Previous and next navigation can be used while the user is in selection mode, as well as in month or year navigation mode.

Navigation by Month

The user triggers month navigation mode by clicking the month link displayed at the top of the date range interval. The currently selected month is highlighted. The user clicks a month to switch the date range interval to the selected month. The user can browse the months by clicking the previous and next arrows.

Navigation by month

Navigation by Year

The user triggers year navigation mode by clicking the year link displayed at the top of the date range interval. The currently selected year is highlighted. The user clicks a year to switch the date range interval to the selected year. The user can browse the years by clicking the previous and next arrows.

Navigation by year

Selection

The calendar date interval control can be set up for single day selection, multiple day selection, or day range selection.

Single day

The user clicks an unselected day to select that particular day and deselect all previously selected days. Clicking a selected day a second time removes the selection. Only one day can be selected at a time. The selected day is highlighted.

Selection – Single day

Multiple days

The user clicks an unselected day to select that particular day. Clicking a selected day a second time removes the selection. Multiple days can be selected. Selected days are highlighted.

Selection – Multiple days

Day range

The user clicks an unselected day to select the start date. Clicking a second unselected day selects the end date. Both start and end dates are then highlighted. The days in between are highlighted in a lighter color. The minimum range is one day and only one range can be selected at a time.

Selection – Day range

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Date Range Selection (guidelines)
Date Picker (guidelines)
Date/Time Picker (guidelines)

Implementation

No links

Date Picker

The date picker lets users select a localized date using touch, mouse, or keyboard input. It consists of two parts: the date input field and the date picker.

Use this control if the user needs to enter a single date or a date range. The control also allows users to navigate directly from one month or year to another.

Usage

Use the date picker if:

You need a range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should know what is selected and jump to the same selection.

Responsiveness

The date picker provides responsive behavior that allows for simple operation on all devices. It is smaller in compact mode and provides a touch-friendly size in cozy mode.

With one click on the input field, the date picker opens in full screen. To close the window, the user can select a date (which triggers the close event), or click Cancel without selecting a date.

Date picker on a smartphone

Date picker on a desktop

Components

The date picker has two components: the date input field and the date picker button. On all devices users can either use the input field to type a date or use the date picker button to open the date picker calendar.

Date picker with input field and button

Date Input Field

In the input field, the user can enter a date directly or select it using the date picker. The system validates the entry and provides the user with feedback. You can also show placeholder text in the field.

Date Picker

With the date picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click or tap the arrows to navigate to the previous and the next day, month, or year view depending on the current view.

The selected date is shown with a blue background. The current day is indicated with a purple border and owns the focus.

Date picker with a selected date and the current date

Clickable areas of the date picker

You can change the default focus “today” to another date. This can save users several clicks when they create events. For an event end date, for example, the focus should propose a date in the future (after the start date).

Use case-specific focus date

Behavior and Interaction

Selecting a Date

The user selects a date by clicking or tapping the date. After the user selects a day, the calendar closes and the date appears in the date input field.

Date selection

Clicking or tapping the arrow shows the next day, month, or year view.

Navigating to the next month

If the current month is clicked, the view changes to the month view and the user can change the month.

Switching to month view

By clicking on a month, the user changes the month and the view changes to the day view.

Selecting another month

The user can similarly change the year. By clicking the current year, the view changes to the year view. After the user selects a year, the view changes back to the day view.

Switching to year view

After the user selects a year, the view changes back to the day view. The date in the date input field stays the same until the user selects a new date.

Selecting another year

Guidelines

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

English (US): January 16, 2022
German (DE): 16. Januar 2022
Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

English (US): 1/16/22
German (DE): 16.01.22
Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format in table cells. Otherwise use the medium format.

If you need to display the weekday, use the full format. For example:

English (US): Sunday, January 16, 2022
German (DE): Sonntag, 16. Januar 2022
French (FR): dimanche 16 janvier 2022

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Responsive Table (guidelines)
Date Range Selection (guidelines)
Time Picker (guidelines)
Date/Time Picker (guidelines)

Implementation

Date Picker (SAPUI5 samples)
Date Picker (SAPUI5 API reference)

Date Range Selection

The control for selecting the date range is a single-field input control. Users can enter a localized date range using touch, mouse, or keyboard input, or by selecting a date range in the calendar. They can also navigate directly from one month or year to another.

Usage

Use the date range selection if:

You need a time range and know that your user is a power user who has to input lots of data. If the keyboard is the primary device used for navigating the app, use two input fields. This allows the user to quickly jump from field to field. By selecting a date in one of the fields, the other field should recognize the information and jump to the same selection.

Do not use the date range selection if:

You want to enter a date and a time. In this case, use the date picker or time picker instead.
The user’s primary goal is not to select ranges. If this is the case, use the simple date picker.

Responsiveness

The date range selection is fully responsive. It is smaller in compact mode and provides a touch-friendly size in cozy mode. For more information about cozy and compact modes, see the article on content density.

Date range selection (size S)

Date range selection (size L)

Components

The date range selection consists of two components: the date range input field and the date range picker.

The two clickable areas of the date range selection on all devices

Date Range Input Field

The user can type the date directly into the input field, or use the date picker. You can also show a prompt text in the field (property: placeholder). The system validates the date and gives the user feedback.

The dates June 7–16 are selected, and June 23 is shown as the current day

Date Range Picker

With the date range picker, the user can see a day view, month view, or year view. The current day and the selected date are highlighted. The calendar week is also visible in the day view. The calendar closes when a final day is selected. The user can click the arrows to view the previous and next days, months, or years (depending on the current view).

The selected date is shown with a blue background. The current day is indicated with a purple border in the calendar.

Clickable areas of the date range selection

Behavior and Interaction

Selecting a Date Range

The user can type two dates into the date range input field or click the calendar icon to open the calendar and select a date. These two possibilities work for all devices – desktops, tablets, and smartphones.

Switch View

Clicking an arrow shows the next or previous day, month, or year.

Navigating to the next month

Clicking the month shows an overview of all months.

Opening the month picker

If the current month is clicked, the user can change the month. When the user selects a month, the view changes to the day view.

Changing the month navigates back to the date picker. The focus is on the last selected start date.

By clicking the current year, the view changes to the year view. When the user selects a year, the view changes to the day view.

Opening the month picker

Selecting a Range

After the user selects a start date, the dates being hovered over turn light blue to provide visual feedback that a range is being selected. When the user selects an end date, the calendar closes. The range appears in the date input field.

Selecting the start date

Selecting the end date

Entering Single Dates

The date range selection also allows the user to input single dates. The user can type one date into the input field, or select the same day as a start and end date in the calendar.

Styles

Delimiter

The delimiter visualizes the start and end date. If no delimiter is given, the app uses the one defined for the used locale.

Placeholder

If no range is selected, show a placeholder text to indicate the correct format. If no placeholder is defined, the control shows the default locale placeholder format. You can define your own placeholder, but you must also take localized versions into account.

Date range selection with default placeholder

Validation

Use in-line validation to give the user feedback, especially in the form of errors and warnings. Possible warning states are warning, error, and success. The date range input field in question is highlighted by a frame in the corresponding color. If the focus is inside the field, an explanation is shown. Ensure that this explanation is as specific as possible.

Visible frame that shows an error when the field is out of focus

Error state with meaningful text; the date range input field is in focus

Guidelines

Display Format

You can choose whether the displayed texts are to be shown in short, medium, or long format, or in another date format like dd–MM–yyyy. However, other date formats (besides short, medium, and long) should be used carefully due to local dependencies.

Long display format

Medium display format

Short display format

Input Types

The following input types are available. (Note: these examples show German date formats for January 14, 2014.)

Unicode CLDR short format: 14.01.14
Unicode CLDR medium format: 14.01.2014
ISO date format: 2014-01-14
ISO date format without delimiters: 20140114
Unicode CLDR short format without delimiters: 140114
Unicode CLDR medium format: 14012014

Date Formats

Long Date Format

Use the long date format for master list/object list item/title and object header/title. Here are some examples:

English (US): January 16, 2022
German (DE): 16. Januar 2022
Danish (DK): 16. Jan. 2022

Short Date Format

Use the short date format for master list/object list item/list of object attributes if space is a concern. For example, you might need to save space if there is a label with the date. Here are some examples of the short date format:

English (US): 1/16/22
German (DE): 16.01.22
Japanese (JP): 22/01/16

Relative and Medium Date Format

If appropriate, use a relative format for master list/object list item/list of object status. For example: today, 1 day ago, 2 days ago, and so on up to 6 days ago. After 6 days, use an absolute date with the medium format.

Use the absolute date with medium format in the corresponding object header in the details area. Do not use the relative format here.

Responsive Table

If screen space is at a premium (for example, if there are too many columns), use the short date format within table cells. Otherwise, use the medium format.

If you need to display the weekday, use the full format. For example:

English (US): Sunday, January 16, 2022
German (DE): Sonntag, 16. Januar 2022
French (FR): dimanche 16 janvier 2022

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Date Time Input (guidelines)

Implementation

Date Range Selection (SAPUI5 samples)
Date Picker (SAPUI5 samples)
Date Range Selection (SAPUI5 API reference)
Date Picker (SAPUI5 API reference)

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

You want to compare objects of the same type with each other over a period of time.
You require responsive behavior.
You have less than 100 lines in the calendar.

Do not use the planning calendar if:

You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
You want to show a complex or graphical representation. In this case, please use the Gantt chart.
You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control 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 the responsiveness is still working.

Planning calendar - Size L

Planning calendar - Size M

Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The example opposite shows what the interaction looks like if the user can trigger multi-select mode. When the user clicks or taps the button, a checkbox appears next to each list item and a Select All option is shown. Additional actions can appear or disappear in the calendar toolbar.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built 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 to smaller size. In this case, the text is cut off rather than truncated.

Switching to Multi-Select Mode

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar

The control consists of different parts:

Toolbar
Header
Calendar view
List item
Row header
Row
Appointment
Interval appointment

1. Toolbar

The toolbar is optional and can contain a title as well as app-specific and generic actions.
If you have actions in the toolbar, we recommend that you use a title to describe the purpose of the planning calendar. For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Add Appointment (icon: add)
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

2. Header

The calendar header has two parts.

Left: An optional switch to see different calendar views (hours, days, months, 1 week, 1 month, or custom) and a Today button, which navigates the visible interval to the present moment, depending on the view
Right: Calandar view

3. Calendar view

The calendar view defines the granularity of the time intervals. You can decide which views are available in the view switch (Hours, Days, Months, 1 Week, 1 Month), and how many values are shown for each view. App developers can change the default number of values shown, but they should then ensure that the app is still responsive.

For all views with the granularity “Days” (Days, 1 Week, 1 Month), you can add a bar to show calendar weeks below the main calendar date interval (property: showWeekNumbers).

The 1 Week view always renders a full week. It displays seven days on one screen. The start date is always the beginning of the week (depending on the locale). It can be found in the view switch as a default view. When applications have this view available, we strongly recommend setting a different number of days displayed in the Days view (more or less than seven). Otherwise, the user might be confused, as the navigation for the two differs.

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

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.

1-month view - Size S

4. List item

The list item contains the row header, row, appointments, and interval appointments. Each row can show different working and 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 for also for non-working days based on specific schedule differences.

5. Row header

This identifies the object for which the appointments are shown. The row header pops in if there is not enough space. It can contain a picture or icon, a title, and a subtitle.

6. Row

All appointments that appear for an object are shown here.

App developers can turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

7. Appointment

Appointments display an icon or picture, a title, and a subtitle. Appointments taking place simultaneously are shown one above the other. There are two appointment sizes – regular and half size. While half-sized appointments save space, they do not show a second line with appointment details.

App developers can define the colors of different appointment types, and appointments can be shown as tentative. Appointments are fully colored.

The control can register the click event, but the app development team must define what happens next.

In 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 is not included in the combined appointments for either calendar week.

You can show the list of the appointments in a combined appointment in a popover. However, this must be implemented by the app team. The control only provides the click event.

The app developer can disable combined appointments by setting the property GroupAppointmentsMode to Expanded.

Users can copy and paste appointments to a new position in the planning calendar using keyboard combinations (Ctrl/Cmd + Drag and drop to the new position).

8. Interval appointment

Each row can also have interval appointments, which are smaller and always appear at the top of the row. Interval appointments can be used to show appointments that last for a prolonged period of time, such as vacations or workshops.

The app developer can choose to hide the space reserved for interval appointments if no such appointments exist for that time period.

Planning Calendar Legend

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

Users open the planning calendar legend using a standard legend button in the toolbar (). Like all other actions in the toolbar, the app developer must add the legend button explicitly.

The app team also needs to decide which container to use for the planning calendar legend. We recommend placing the legend in a popover to keep the context. You can also use a dialog, or, if there is sufficient screen real estate, show the legend as dynamic side content.

The planning calendar legend has two non-collapsible sections containing legend elements. By default, these are called Calendar and Appointments. The app developer can configure the section names using the itemsHeader and appointmentItemsHeader properties. If no elements are available for a section, it is not displayed.

The Calendar section contains standard legend items: Today, Working Day, Non-Working Day, and Selected (only in the 1-month view on mobile). The app team must ensure that the Selected element is added to the planning calendar legend when the planning calendar is viewed in 1-month mode in a smartphone size. This is not provided by the control. If any of the standard legend items are not needed, you can switch them off (property: standardItems).

You can also apply colors for special days in the Calendar section. The planning calendar legend does not automatically use the colors defined for special days in the planning calendar – this must be done by the app team.

The Appointments section contains the color values for the available appointment types. The app developer has to define explicitly which color represents which type. The planning calendar legend does not take the color automatically from the planning calendar.

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.

Planning calendar with legend

Developer Hint

To prevent waiting time, app developers should load the sap.ui.unified library.

Behavior and Interaction

To create an appointment, the user must trigger an action by clicking the Add icon in the toolbar. Clicking directly on the row also creates a new appointment.

The user can click on the appointment to see further details. The app development team must define what kind of information is then shown. For example, clicking on an appointment can trigger a popover with detailed information.

A multi-select toggle can also be provided in the toolbar. This can be used, for example, to select multiple people in order to delete them from the planning calendar.

Various tooltips can be shown, but you should not use them to show additional information because users cannot access this functionality on touch devices.

Depending on the current time interval, appointments might be smaller and the text might be cut off, rather than truncated. The user can click or tap the appointment to see the details.

1. View select

The user can change the calendar view with the select control (dropdown). For example, to get an overview of a whole year, the user selects the Months view. Which view is most useful depends on the average length of appointments and the use case.

2. Today action

The user can trigger this action to go back to the current date/moment.

3. Back and forward navigation

The arrows allow the user to navigate to the next or previous interval.

4. Picker

The user can open a date picker to select the start time for the visible interval. What is shown initially in the picker differs depending on the view.

5. Month switch

The month switch is available if the day or month view is selected. It allows the user to switch to a different month.

6. Year switch

Day, month, and year views enable the user to switch between different years.

Navigation parts

Interaction Flow for Switching Days

There are two ways in which the user can switch to a different day:

Clicking or tapping the arrows to navigate to the next or previous interval.
Clicking or tapping the date opens the date picker. When the user selects a day, the picker closes and navigates the user to the selected value.

Switching to a Different Day

Snapping Header

The header area of the planning calendar can remain fixed on top of the screen (property: stickyHeader), which allows users to view calendars with a lot of rows without losing the context.

Header snaps to top when scrolling down

Drag and Drop

Drag and drop can be used to move appointments (to enable Drag and Drop use 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 and change the time from 2:00-3:00 PM) . When dragged, the appointment is shown as a ghost element on the mouse cursor. Drop target areas are indicated to the user with a placeholder.

In the “Hours” view, the appointments can be moved to a specific new time, with the placeholder snapping at every 30 minutes. In the “Days” view, the appointment can be moved to a different day. The placeholder indicates the target day. On drop the appointment is moved to that day but keeps its previous start and end hour. The interaction is the same for the “Months” view. The placeholder indicates the target month and, when dropped, the appointment is moved to that month. The start and end hour and start and end day remain the same.

Appointments can be moved between rows. Note that additional coding may be needed to determine whether all calendar users will be able to perform this action.

Users can create new appointments by clicking, dragging and releasing on an empty space in the content area. The control also allows users to change the duration of an appointment by clicking and dragging one side of the appointment container. These two options are only available for desktop devices.

Combined appointments and interval appointments are not draggable.

Drag and drop is only available on supporting browsers.

Drag and drop

Guidelines

Switching the Row Header

To enable end users to rearrange the planning calendar by switching the row header, you can implement a flexible row header. This is not done by the control and must be implemented by the app development team.

The list items in the row header can be a value of any attribute of an appointment. The appointment attributes are part of app-specific content, so they should be specified by the app development team. The control does not provide default attributes.

Our guideline is to use the select control in the place of the calendar title. The select control will contain all the attributes that can serve as the row header. When a different attribute is selected, 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.

It is also possible to have both the calendar title and select control, in which case you should have first the title and then the select.

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

Select Control in Row Header

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Overview Toolbar (guidelines)
Calendar Date Interval (guidelines)
Date Picker (guidelines)

Implementation

Planning Calendar (SAPUI5 samples)
Planning Calendar (SAPUI5 test suite)
Planning Calendar Row (SAPUI5 API reference)
Planning Calendar View (SAPUI5 API reference)

Input Field

A text input field allows users to enter and edit text or numeric values in one line. To help users enter a valid value, you can enable the autocomplete suggestion feature and the value help option.

For more information on which selection control to choose, see the selection control overview.

Usage

Use the input field if:

The user needs to enter a short, single-line text or number.
The user needs to enter a password, URL, phone number, or email address.
The user needs to select a single item from a large amount of data (for example, more than 200 items).
The user needs to find an object by searching for more than one attribute, such as an ID, city, and customer name. Use this control in combination with the autocomplete suggestion feature and value help option. For a small set of values (for example, fewer than 20 items), consider using the select control. Otherwise, use the combo box (for 20-200 items).

Do not use the input field if:

The user needs to enter dates and times. In this case, use the date picker, date range selection, or date/time picker.
The user needs to enter long texts. In this case, use the text area.
The user needs to carry out a search. In this case, use the search field.
The user needs to select multiple values. In this case, use the multi-combo box (for fewer than 200 items) or the multi-input field (for more than 200 items).

Responsiveness

In the examples below, the input field is shown in combination with the tabular autocomplete feature for different device sizes.

Size S (Smartphones)

Cozy mode:

When the user clicks or taps the input field, a new full screen dialog opens in which suggested items can be selected. Here, the pop-in feature of the responsive table is used.

Tabular autocomplete suggestion feature on a smartphone

Size M (Tablets)

Cozy mode:

The pop-in feature of the responsive table is used here, and defined columns are wrapped into a new line due to the limited space available.

Tabular autocomplete suggestion feature on a tablet

Size L (Desktops)

Compact mode:

The full table is shown by the suggest feature.

Tabular autocomplete suggestion feature on a desktop

Types

Six input types are currently supported (API). Be sure to select the correct type for your use case. Depending on the input type, a different keyboard layout is displayed on a mobile device (see some sample input types).

Note: The control does not provide validation based on the type. The app development team must carry out format validation. If binding is used, validation is carried out by the model, but the error handling still needs to be taken care of on the UI.

URL

Input type URL – Keyboard layout on a smartphone

Telephone Number

Input type telephone number – Keyboard layout on a smartphone

Password

Input type password – Keyboard layout on a smartphone

Some types, such as number or telephone number, can be used together with mask input for better guidance.

Examples of input with different number masks

Behavior and Interaction

Entering Text Using the Autocomplete Feature

Have a look at the interaction flow below:

Entering Text Using the Value Help Dialog

Have a look at the interaction flow below:

Value Help Dialog on Mobile

Value Help Dialog on Desktop

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

An input field can have four states: default, warning, error, or success.

Default

Error

Warning

Success

Properties

Value State and Value State Message

The input control offers the four value states listed below. For the error and warning states, you can show an additional value state text when the focus is on the input field.

None (default): No value state message is shown.
Warning
Error
Success: No value state message is shown.

For more guidance on when to use which state, check out the article on message handling.

Default

Warning

Error

Success

Required

Use this property to indicate that user input is required. Set the property for the specific input field to ensure that the asterisk is shown in front of the label.

Required input field

Maximum Length

Use this property to set the maximum number of characters allowed. There is no limit by default.

Placeholder

The placeholder, or input prompt, is a short hint (a word or short phrase) to help the user with data entry. A hint can be a sample value or a brief description of the expected format.

Placeholder

Description

You can provide an additional description on the input field, for example, for units or currency. The width of the input field and description is distributed equally by default. Although the default setting is 50%, you can change this with the fieldWidth property.

Input description

Width

The width of the input field is set to 100% by default. Input fields are usually used in forms, where the width is determined by the form element or container that the input field is embedded in. Therefore, we do not recommend defining a fixed width, but rather working with proper layout containers, like the form, simple form, and responsive grid layout, and with the layout data property, where the width is defined by the 12-column approach.

Editable and Enabled States

The input field has three states (see examples of input states):

Enabled: This is the default setting.
Read-only: The input field is not shown; only the value is shown. This is used in display-only forms.
Disabled: The input field is shown with a visual indication that an edit is not possible, for example, due to missing editing rights.

Editable and enabled input states

Text Alignment

The input field offers six types of alignment for text values (API):

Begin
Center
End
Initial (default): Browser-configured alignment is used
Left
Right

Value Help

To help the user find the correct value, you can enable the value help option (property: showValueHelp). By enabling this option, a small value help icon is displayed in the input field on the right-hand side. Once this option is enabled, the click event can be registered and one of the following displayed:

Select dialog (simple)
Value help dialog (complex)

If you want to force the user to select only existing values, you can enable the value-help-only option (see an example of the value-help-only option). In this case, the user cannot enter text in the input field. Instead, the value must be selected from the list of suggestions, or chosen using the select dialog or value help dialog.

Value help option

The values can also be pasted into the input field by copying and pasting, or dragging and dropping, if the user prefers this. In this case, the values will be automatically transformed into conditional expressions. Example: Copying values “1234” and “5678” leads to the token generation “=1234” and “=5678”. Additionally, these values will be found within the conditions tab of the value help dialog.

Autocomplete Suggestion

The input control offers three different types of autocomplete suggestions: single, two-value, and tabular. The width of the autocomplete and the input fields are set by default, but you can change these via the maxSuggestionWidth property. The position of the suggestion box depends on the space available below the control. If there is not enough space, the suggest box is shown above the control.

Single Value with Autocomplete

Displays a list of suggestions with one left-aligned value. As a base for the aggregation suggestionItems, sap.ui.core.Item is used.

See live example of single-value autocomplete suggestions.

Single value autocomplete suggestion feature

Two Values with Autocomplete

The two-value autocomplete suggestion feature displays two attributes of a business object, such as an ID and a name. As a base for the aggregation suggestionItems, sap.ui.core.ListItem is used.

The text property is displayed first, left-aligned, and the additionalText property is right-aligned.

See live example of two-value autocomplete suggestions.

Two-value autocomplete suggestion feature

Tabular Autocomplete

This autocomplete feature displays the values in a table layout. The width of the columns is distributed equally by default.

To use the tabular autocomplete feature, use the suggestionColumns aggregation to define the columns and the correct responsive behavior for the pop-in. For more information, see the article on the responsive table.

With the showTableSuggestionValueHelp property, you can offer a Show All Items button at the end of the suggest result list. Because the number of results in the suggest functionality is limited, this option helps the user find the relevant item via an alternative dialog:

Select dialog (simple)
Value help dialog (complex)

See a live example of tabular autocomplete suggestions.

Tabular autocomplete

Guidelines

Always provide a meaningful label for any input field, and use the least complex control (such as select instead of value help. Use more intricate controls only if the use case really requires it. Where appropriate, help users by providing mask input or placeholder texts.

Maximum Columns

For input fields in a tabular view, we recommend using a maximum of 4 columns.

Maximum Length

Limit the length of the input field. For example, if you don’t want users to enter more than 5 characters, set the maximum length to 5. The maximum permissible character length is not defined by default. If the back-end system has a limit, ensure that you set this property accordingly.

Note that this parameter is not compatible with the input type sap.m.InputType.Number. If the input type is set to Number, the value of the maxLength property is ignored.

Placeholder

Avoid using the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible.

Description

The description field should be used, for example, for displaying units or currency. Do not use a description for help text or as a label replacement. Note that the description is not placed in a new line in size S. Therefore, only use the description property for small input fields with a short description.

Width

Avoid setting a fixed width, but rather embed it in a proper layout (such as a form, simple form, or grid layout) and use the layout data property to define the responsive behavior for sizes S, M, and L:
- Simple form – See a live example of a simple form and code snippet.
- Form – See a live example of a form.
- Grid layout – See a live example of a grid layout and code snippet.
Ensure an appropriate width for the range of values to be entered for the sizes S, M, and L. Keep in mind that word length can vary between languages, so take localization into account.

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.

Text Align

Align left if:

Text is used. Also use left alignment for a phone number, URL, password, and email address.

Align right if:

Amounts and decimal numbers are used.
Values need to be added and compared.

Value Help

Show the value help option to help the user select the correct value (such as a customer ID) from a large dataset via the:

Use this option in combination with the autocomplete suggestion feature.

When the user clicks or taps the value help icon, the data entered into the input field must be transferred to the processing dialog so that the user does not have to enter the search term again. Likewise, data entered in the processing dialog must be transferred back to the input field.

Autocomplete Suggestion

Use the autocomplete suggestion feature to display real-time suggestions and to help the user enter information more accurately and efficiently. If you expect the suggest values to be longer than the input field itself, you can change the width via the maxSuggestionWidth property.

Single Value with Autocomplete

Use the single-value autocomplete feature if you want to search by only one attribute, such as an ID or a customer name.

Two Values with Autocomplete

Use the two-value autocomplete feature if you want to search by two attributes, such as a customer name and an ID. This ensures that the search is carried out for both attributes.

Tabular Autocomplete

If you need to display more than two attributes, use the tabular autocomplete feature. Try to keep the number of columns to a minimum, and focus on the columns that are really relevant for the use case. Define appropriate responsive behavior for sizes S and M. For more information, see responsive table.

The width of the columns is distributed equally by default. To avoid truncation, accurately estimate the primary attribute length and set a minimum width for this column.

Creating and Editing Objects

Sometimes a new object needs to be created if the user cannot find a specific item via autocomplete or value help. In this case, we recommend that you place the New action next to the input field.

If you want the user to be able to edit a selected object directly, you should place the Edit link next to the input field.

If both actions are needed, they should be toggled based on the content of the input field. If a valid object is selected, you should display Edit. If the input field is empty or the object is not valid, you should display New. This pattern can also be applied for the multi-input field, combo box, multi-combo box, and select controls.

Input field – New action

Input field – Edit action

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Select Dialog (guidelines)
Value Help Dialog (guidelines)
Combo Box (guidelines)
Select (guidelines)
Multi-Input Field (guidelines)
Date Range (guidelines)
Date/Time Picker (guidelines)
Multi-Combo Box (guidelines)
Dialog (guidelines)

Implementation

Input Field (SAPUI5 samples)
Input Field (SAPUI5 API reference)

Select

The select control (also known as a dropdown) is commonly used to enable users to select an item from a predefined list.

For more information on which selection control to choose, see the selection control overview.

Usage

Use select if:

Users need to select one item exclusively from a short list of options (for example, fewer than 12 items).
The values of the option list are of secondary importance and do not need to be displayed right away.

Do not use select if:

Users need to choose between two options, such as On or Off and Yes or No. In this case, consider using a switch control instead.
Users need to pick one item from a very large set of options. In this case, consider using the combo box instead.
You need to display more than one attribute. In this case, consider using the input field with a select dialog or a value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the input field with select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using radio buttons or a radio button group instead.

Responsiveness

The display of the select control depends on the device. On smartphones, the selection list takes up the whole screen. On desktop and tablet devices, it appears as a popover.

Size S

Select option list in full screen - Size S

Size M

Select option list – The option list opens above the field if there is not enough space below it - Size M

Size L

Select option list – The option list opens above the field if there is not enough space below it - Size L

Layout

The select control can be placed in toolbars, such as chart toolbars, footer toolbars, or header toolbars, as well as in forms or tables:

Components

Select Trigger

The trigger to open the option list is either the Select field (1), which also displays the current selection, or an icon (3).

Option List

The option list (2) displays all the items available to the user. The selection is always highlighted. Selecting another option from the list moves the highlight to the selected option.

Full Screen Title Bar for Size S

Opening the select control on a smartphone brings up the option list in full screen mode. The full screen mode can be closed using the icon on the top right corner (5).

You need to set a title for the full screen mode (4). We recommend the following format:

Single selection

Select [Entity]

Example: Select Product

Multi-selection

Select [Entities]

Example: Select Products

Anatomy of the select control

Anatomy of the select control - Size S

Behavior and Interaction

Clicking/Tapping

The Select field always displays the current selection. The user clicks or taps the field to display a list of options to choose from. Once the user selects an option, the list box closes and the selected option is displayed in the field. If there is no Select field but an icon, the user clicks the icon to open the list of options. The currently selected item is always highlighted in the list to help the user identify what has been selected.

Guidelines

Option List

The option list contains text values only. Keep the text values as short as possible because the list uses single lines only. Values that are too long may be truncated.

If you need to indicate that none of the selection options are selected, or you need to allow the user not to select an option, provide (None) (1) as an option and place it at the beginning of the list.

If you need to indicate that all items apply, for example, as a list filter, provide All as an option and place it at the beginning of the list.

If your use case requires a blank input field instead of (None), use a combo box instead.

If the select control is placed in a toolbar as an icon-only version for grouping or filtering a set of items, consider the following guideline:

Sort, Group, and Filter:

(Not sorted)
Note: In most cases, this option is not necessary; just show the default sort settings instead.
(Not filtered)
(Not grouped)

For more information about the toolbar, see toolbar overview.

Define a default selection whenever possible (2). If the selected item is not specified, the first one is selected.

(1) Selection option list with (None); (2) first value selected

Label

The select control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label.

Information

Do not provide a blank value to indicate that nothing is selected.

Sorting

The sort option list contains all the items that are available to the user. Choose one of the following styles to order the content:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first, followed by less common options. Sort the options alphabetically if more than eight select options are available. This helps the user find the right option quickly.

Example of logical sorting

Alphabetical: Sort currencies, names, and similar content alphabetically.

Example of alphabetical sorting

Numeric: Sort numeric values into a sequential order, with the lowest number first.

Example of numeric sorting

Chronological: Sort time-related information into chronological order, with the most recent first.

Example of chronological sorting

Width

You can adjust the width of the option list to some extent. The width of the select control is set to Auto by default, while the maximum width is set to 100%. The option list adapts its length to the longest entry by default.

The select control is usually used in forms, where the width is determined by the form element or container in which the select control is embedded. Therefore, we do not recommend defining a fixed width, but rather working with proper layout containers, like the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined.

If you need to restrict the width to a defined value, set the width accordingly.

Do not allow the control to auto-adjust based on the selection.

Keep in mind that there is no horizontal scrolling in the option list. Entries in the list that are too long are truncated and users will not be able to read them.

Information

If localized text is not an issue, such as with currency codes, consider using a smaller width.

Unit of Measurement

You can use the layout options of the form to can add the unit of measurement (UoM) after select. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Multi-Combo Box (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)

Implementation

Select (SAPUI5 samples)
Select (SAPUI5 API reference)

Toolbar Overview

The toolbar enables the user to change the UI or trigger an action. For example, the toolbar allows the user to change views, manipulate data or objects, navigate to another page, perform generic actions, and so on.

This article gives an overview of what kind of different toolbars exist and when to use which one.

Information

With SAPUI5 version 1.40, the floating footer toolbar was introduced to improve the legibility and general clarity of the page. It is slightly transparent, showing underlying content. The floating footer property is activated at page level and not at the floating footer itself.

Actions and Layout

Actions can be used as follows:

They can be independent of the current selection and not related to a specific item or object. (1)
They can be specific to the current object (user selects one item). (2)
They can apply to a set of items (user selects two or more items). (3)
They can control the settings of the UI, which affects all items. (4)

Types of actions

Sort your buttons according to their importance for the user, with the most frequently-used action first and the most seldom-used action last. All buttons go into the overflow from right to left, thus ensuring that the most important buttons are the last to be moved into the overflow menu.

The toolbar is mostly used for buttons (with an icon or text) and should be right-aligned.

Responsiveness

To enable responsiveness, use the OverflowToolbar control. Based on the sap.m.Toolbar control, the OverflowToolbar control is a container that provides overflow when its content does not fit in the visible area. Controls that can overflow include the segmented button, select, toggle button, checkbox, input, search field, combo box, and date/time input.

Only allow important actions to shrink and stay outside the overflow. The app team itself must decide which actions it considers to be sufficiently important.

The height of the toolbar changes on desktops (compact mode), tablets, and smartphones (cozy mode). For more information, see the article on content density.

Responsive table toolbar – Size S

Responsive table toolbar – Size L

Behavior and Interaction

App teams should implement overflow behavior to ensure that all actions can be accessed at any time. Buttons are sorted by usage, with the most frequently used action first (on the left) and the most seldom-used action last (on the right). This ensures that the most important buttons are the last to be moved into the overflow menu. Our general guideline is to use only icon buttons or text buttons. Do not combine an icon and text into one button. Buttons are always right-aligned.

Overflow (Generic)

The overflow should be activated either when there is not enough space for all actions, or if some actions are less important than others. In this case, the app team might decide to have certain actions only appear in the overflow. Furthermore, the app team can also decide that some (important) actions should never be moved into the overflow.

When you implement the overflow toolbar, the overflow behavior is generated automatically. Since release 1.30, new features have been added to the overflow toolbar. The “…” (overflow) button is now a toggle button and can be used to switch the overflow menu on and off.

The user clicks or taps the overflow button to open a popover. In this action sheet, all icon buttons are labeled with text and the user can overflow the following controls:

sap.m.SegmentedButton – When in the overflow, the segmented button is in select mode and looks like a select, although it is technically still a segmented button.
sap.m.Select – When in the overflow, it is always in default mode to take advantage of the extra space, even if it was set to icon-only mode in the toolbar.
sap.m.ToggleButton
sap.m.Checkbox
sap.m.Input
sap.m.SearchField
sap.m.ComboBox
sap.m.DateTimeInput
sap.ui.comp.smartfield.SmartField
sap.m.Label
sap.m.MenuButton

All buttons go into the overflow from right to the left. This ensures that the most important buttons are the last to be moved into the overflow menu.

Prioritization

You can also prioritize the actions in the toolbar by applying one of five statuses:

Always overflow: The action always goes into the overflow.
Disappear: An action that is not so relevant for the user can disappear if the space is limited (for example, a title).
Low: Assign the priority “Low” to an action if the user seldom needs it; this action will overflow first.
High: Actions set to “High” remain visible in the toolbar until all lower-priority actions have moved to the overflow. Lower-priority actions are those with the priorities “Disappear” or “Low”, and all unprioritized actions.
Never overflow: These actions are always visible in the toolbar.

The priority of each item is high by default. If two items have equal priority, the item on the right side overflows first.

Grouping

Items can overflow together even if they are in different positions. This can be achieved using the group property in the overflow toolbar layout data. When the value of the property is 0, the element does not belong to any group. When two or more elements are given the same property value, they belong to the same group and will go into the overflow together. Elements that belong to a group are not allowed to have “always overflow” or “never overflow” as priorities, since these priorities force the items to remain either in the toolbar or in the overflow area. When group elements have different priorities, the priority of the group is defined by the maximum priority of its elements.

Table toolbar on desktop without overflow

Table toolbar on smartphone with overflow

Table toolbar on smartphone with open overflow

Styles

The footer toolbar has a dark background, while header and content toolbars have a transparent style. Buttons are always transparent, and the styles accept, reject, and emphasized are reserved for key actions on the page. Pages will either have a styled button in the header or in the footer toolbar.

For more information, see buttons.

The toolbar style is an enumeration with two properties: Standard (default) and Clear.

Standard style results in linear design (with border) and is intended for standalone usage of the toolbar.
Clear style appears as a plain color without borders. This style visually groups the toolbar with a nearby control or controls.

The toolbar style property is combined with the toolbar design property to create various visual styles.

Types

A variety of toolbars exist for different use cases (see examples below). The following types are used:

Header toolbar: Contains global actions that are important for the whole page
Footer toolbar: Contains only closing and finalizing actions
Table toolbar: Toolbar that is positioned above a table and contains table-specific actions
Chart toolbar: Toolbar that is positioned above a chart and contains chart-specific actions
Info bar: Blue toolbar that indicates what filters have been set, and how many items have been selected

Header Toolbar

Header Toolbar with Edit and Delete Action

Footer Toolbar

Footer toolbar with transparent standard buttons and emphasized

Table Toolbar

Table toolbar with title, show items, sort, group and settings

Chart Toolbar

Chart toolbar with perspective switch, legend, zoom, full screen, view switch

Info Bar

Info bar in filtered master list

Guidelines

Order of Buttons

To provide a consistent user experience for each app, we highly recommend using the following alignment for generic actions:

All buttons are right-aligned.
Text buttons should be grouped together, as should icon buttons.
App-specific text-only buttons and generic text-only buttons can be combined and arranged in a sequence defined by the app team. Remember to place the most frequently-used actions furthest to the left of the group of buttons. This ensures that these actions are the last to be moved into the overflow menu or are visible at all times.

General Guidelines

Do not overload the toolbar with actions.
Place actions as close to the corresponding content as possible.
Place commands in the same location throughout the app. Each page should contain only the commands that are relevant to that page. If commands are shared between pages, they should be placed as close to the same location as possible on each page so that users can predict where the commands can be found when navigating.
Separate navigation and commands. Place commands as close to their corresponding items as possible.
Do not place Settings, Logout, or other account management commands in the footer toolbar. All these actions are shown in the Me Area.
Use only icon buttons or text buttons. Do not combine an icon and text into one button. Buttons are always right-aligned.
If you want to group buttons, use a menu button.
Actions that impact the entire page are placed in the header area.
Only closing or finalizing actions are placed in the footer toolbar (for example, Submit or Post).

UI Text Guidelines

Use tooltips such as Sort, Filter, and Group to label the icons in the footer toolbar. In the case of Sort, Group, and Filter, use the following text for the no selection made option:

(Not sorted)

Note: In most cases, (Not sorted) is not necessary. Simply show the default sort settings instead:

(Not filtered)
(Not grouped)

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Button (guidelines)
Footer Toolbar (guidelines)
Table Toolbar (guidelines)
Chart Toolbar (guidelines)
Header Toolbar (guidelines)

Implementation

Toolbar (SAPUI5 samples)
Overflow Toolbar (SAPUI5 samples)
Toolbar (SAPUI5 API reference)
Overflow Toolbar (SAPUI5 API reference)

Multi-Input Field

A multi-input field allows the user to enter multiple values, which are displayed as tokens. To help the user enter a valid value, you can enable the suggestions feature and the value help option.

Usage

Use the multi-input field if:

You want the user to select multiple ranges (with the value help option and the value help dialog).
The dataset to choose from is expected to increase over time (for example, to more than 200 values).
You need to provide the value help option to help users select or search multiple business objects.
You want to enable users to add custom values.

Do not use the multi-input field if:

You want the user to select one entry only. In this case, use the input field or combo box instead.
You want the user to select from a pre-defined set of options only. In this case, use the multi-combo box instead.

For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

Cozy mode.
When the user taps the multi-input field, a new full screen dialog opens. After tapping in the input field and typing, the suggestions can be selected. When the user makes a selection, the dialog closes and the token is displayed.
The user can review the tokens by swiping them to the left or right.

Suggestions on a smartphone (size S)

Users can review tokens by swiping left and right on touch devices

Size M

Cozy mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by swiping them to the left or right.

Suggestions on a tablet (size M)

Size L

Compact mode.
The suggestions appear below or above the multi-input field.
The user can review tokens by pressing the right or left arrows on the keyboard.

Suggestions on a desktop (size L)

Types

The input types of the multi-input field are identical to those of the input field.

Behavior and Interaction

Adding a Token

The user can add a token using suggestions or value help. When an item is selected from the suggestions dropdown, the corresponding token is created, and the input field is ready for the next entry. Tokens are placed next to each other on one line.

Developer Hint

Values that are entered can also be tokenized when the user presses ENTER. The app development team can perform a custom validation of the entered data and decide whether a token should be created.

Adding tokens

Adding a second token

Information

For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Reviewing Tokens

If tokens have been selected, and the input field is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking or tapping the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking or tapping its checkbox or label.

Multi-input field - n More (Desktop)

Multi-input field - n More (Phone)

In the input itself, the user can review tokens by using the left or right cursor keys on a desktop, or by swiping to the left or right on a smartphone or tablet.

Left/right keyboard cursor

Swiping left and right on a touch device

Deleting Tokens

The user can delete tokens by pressing the Backspace or Del button (when selected) on a desktop’s keyboard, or by tapping the Delete icon on a mobile device.

Deleting tokens

Using Value Help

You can enable the value help option to provide a more advanced dialog for finding the relevant business object. Two dialogs can be used at present:

Select dialog (simple)
Value help dialog (complex)

Value help with select dialog

Value help with value help dialog

Filtering

When the user starts typing in the input field, the list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

Multi-input field - Default filtering

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input field can handle paste actions containing multiple items, such as items that have been selected in a column of a spreadsheet or text file. The user simply selects a whole column in the spreadsheet, copies it, and then pastes it from the clipboard into the multi-input field. Each item is represented as a token. If a single value is copied and pasted into the field, it is shown as a text value, as further editing might be required before it is converted into a token.

Guidelines

Give the control a width that is appropriate for the range of values that are going to be entered. Try to avoid setting a fixed width on this control. Instead, embed it in a proper layout (such as a form, simple form, or grid layout) and work with the layout data property.
Provide meaningful labels for all input fields. Do not use the placeholder as a replacement for the label. The placeholder should only provide an additional hint.
The multi-input field can currently contain tokens and one free text value. If you allow only validated values, display an error or warning when the user tries to leave the field to indicate that the value entered is invalid, or remove the value.
If users try to select an item that has been selected before, we recommend setting an error state and providing a meaningful message.

Multi-input - Error state for an item that has already been selected

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

The multi-input field can be used in the grid table, analytical table and tree table as well, as condensed mode is already supported, both for desktop and mobile (tablets).

Multi-input field in the grid table in condensed mode

Properties

Since the multi-input field is derived from the input field, refer to the properties in the input field article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Multi-Combo Box (guidelines)
Input (guidelines)
Combo Box (guidelines)
Select (guidelines)
Select Dialog (guidelines)
Value Help Dialog (guidelines)
Tokenizer (guidelines)

Implementation

Multi Input (SAPUI5 samples)
Multi Input (SAPUI5 API reference)

Combo Box

The combo box control allows users to select an item from a predefined list.

The control provides an editable input field for filtering the list, and a dropdown menu with a list of the available options.

Usage

Use the combo box if:

Users need to select a single item from a long list of items (minimum 13, maximum 200 entries).
The values of the option list are secondary information and do not need to be displayed right away.

Do not use the combo box if:

Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a switch control instead.
Users need to pick one item from a small set of options, such as up to 12 entries. Consider using the select control instead.
Users need to pick one item from a large set of options, such as more than 200 entries. Consider using the input field control with a select dialog or value help dialog instead.
You need to display more than one attribute. Consider using the input field with select dialog or value help dialog.
Searching on multiple attributes is required. Consider using the input field with select dialog or value help dialog.
Your use cases require that all available options should be displayed right away without any user interaction. Consider using radio buttons or a radio button group.

For more information on which selection control to choose, see the selection control overview.

Responsiveness

Size S

Size M

Size L

Also see the section on mobile handling below.

Components

Title

A descriptive heading (1).

Input Field

The input field (2) displays the selected value. Users can type any character to filter the option list.

Dropdown Arrow

The dropdown menu’s arrow (3) collapses and expands the option list.

Option List

The option list (4) contains a list of values (5) that users can choose from.

Size S

Size M/L

Two-Column Layout

Use the combo box with a two-column layout if you need to display additional information for the selection options, such as currencies, country abbreviations, or system abbreviations.

Users can filter both columns simultaneously showing only matching entries.

Combo box with two-column layout

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Select the item directly from the dropdown list.
Type the item into the input field.
Use the up and down arrows to navigate the list.

Clicking the input field places the cursor in the field (1). Clicking the arrow opens the option list (2). When the user starts typing, the list is filtered accordingly. The first item that starts with the characters entered is highlighted in the list and auto-completed in the input field (3). Up/down moves the highlight in the list and populates the value in the field (4). Selecting a value closes the list of options (5).

Auto-Complete

When the first few letters are typed in the input field, the control performs auto-complete to help users to easily select one item from the option list.

Choose from Option List

The option list displays all the available items the user can choose from. The selection is always highlighted. Selecting another option from the list moves the highlight to the newly selected option.

Clicking the arrow opens the option list below the field. If there is not enough space, the list is displayed above the input field.

Selecting a value

Filtering the Option List

When the user starts typing in the input field, the option list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

If the filtered option list contains items that start with the characters entered by the user, the first matching, unselected item is auto-completed in the input field.

Combo box - Default filtering and auto-complete

Combo box - Default filtering in both columns and auto-complete

Auto-Resize

The width of the option list adapts to its content. The minimum width is the input field plus the dropdown arrow. The maximum width is the part of the screen furthest to the right. If the option list content requires even more width, entries become truncated.

Option list – Minimum width

Option list adapts to long entries

Mobile Handling

The user can enter text into the input field (supported by auto-completion). Clicking or tapping on the dropdown arrow of the combo box (1) opens in a full-screen dialog (2). The user can now modify the selected entry by tapping the input field of the combo box. The mobile keyboard is then displayed, and the user can begin to enter a new term to filter the option list, also supported by auto-completion (3). The option list closes when the user clicks or taps the OK button at the bottom of the list (4) or selects an item in the list (5).

Information

For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

A combo box has different styles for its different states. Here are some examples:

Unselected

Unselected (predefined placeholder)

Unselected (on hover)

Arrow (on hover)

Focus

Warning

Error

Expanded

Auto-complete

Guidelines

Label

The combo box control can be displayed with or without a label. If the field is attached to another field, you do not need to define a second label. For more information, see the article on how to use labels in SAP Fiori.

Placeholder

Do not use the placeholder attribute as an alternative to a label. This is important because the placeholder text is overwritten as soon as the form is filled out. Labels are necessary to indicate the meaning of the form fields when the placeholders are no longer visible. Show a placeholder only if the user needs a hint on data entry. Do not repeat the content of the label. A hint could be a sample value or a brief description of the expected format. Read more about how to use placeholders.

Option List

The option list contains text values only. Keep the text values short because the list is represented using only single lines. Values that are too long might be truncated.

If you need to express that none of the selection options are selected, show a blank input field. Define a default selection whenever possible.

Sorting

We recommend sorting options alphabetically to help users find the right option quickly. For more sorting rules, check out the guidelines for the select control.

Width

You can adjust the width of the option list to some extent.

The combo box control is usually used in forms, where the width is determined by the form element or container in which the combo box control is embedded. Therefore, we do not recommend defining a fixed width, but rather working with proper layout containers that have a defined width, such as the following properties: “form”, “simpleform”, “responsivegridlayout”, and “layoutdata” .

If you need to restrict the width to a defined value, set the width accordingly.

Keep in mind that there is no horizontal scrolling in the option list. Entries in the list that are too long become truncated and users may not be able to read them.

If localized text is not an issue, consider using a smaller width.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the combo box control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Properties

Selection

When you select a value, there are two events:

Change: Occurs when the text in the input field is changed and the focus leaves the input field or the user presses the Enter key.
Selection change: Occurs when the user types something that matches an item in the list; also when the user clicks a list box item, or when navigating via keyboard.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Select (guidelines)
Multi-Combo Box (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Switch (guidelines)

Implementation

Combo Box (SAPUI5 samples)
Combo Box (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multi-selection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.
You want to enable users to add custom values. In this case, consider using the multi-input field.
Your use case requires more options to choose from. In this case, consider using the multi-input field, either with the select dialog or value help dialog (for more than 1000 items).

For more information on which selection control to choose, see the selection control overview.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Also see the section on behavior for mobile devices.

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of for an entry closes the option list and creates a token for the selected option. To enable multi-selection, every entry also has a checkbox (4). Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click or tap the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks or taps the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4), while the typed text remains in the input field. Selected options are automatically entered into the input field as tokens (5).

If the user selects items from the filtered option list (3) by clicking or tapping the checkbox or by pressing the spacebar of the keyboard, the text entered in input field remains. The option list stays open. If the user selects items by clicking or tapping the label or by pressing Enter, the entered text is cleared and the option list is closed.

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If the user tries to enter character combinations that are not in the option list, visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Reviewing Tokens

If tokens have been selected, and the multi-combo box is not in focus, the input field displays as many tokens as possible in the available space. If more tokens have been selected, an [n] More label indicates the number of hidden tokens. The tokens in the input field appear in the order in which they were selected.

Clicking or tapping the [n] More label opens a popover below the input field, in which all selected items are shown. The user can deselect an item by clicking or tapping its checkbox or label.

Multi-combo box - n More

Filtering the Option List

When the user starts typing in the input field, the option list is filtered. Only items that match the characters entered are shown in the dropdown list. The default filtering method is “starts with per term”, which matches the beginning of each word in an item’s text.

In addition, application developers can set a custom filtering method “starts with” or “contains” (method: setFilterFunction). The “starts with” approach filters only for items where the beginning of the label matches the query entered. The “Contains” approach searches the full label for a match.

As a visual hint for the user, the matched characters are highlighted in the option list items. The highlighting works on the basis of “starts with per term”, regardless of the filtering method.

If the filtered option list contains items that start with the characters entered by the user, the first matching, unselected item is auto-completed in the input field.

Multi-combo box - Default filtering and auto-complete

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Tapping the Arrow

Tapping the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Left: Filter bar with multi-combo box; Right: Full screen multi-combo box selection

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered using the default “starts with per term” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected options only.

Left: Option list, filtered by user input; Right: Selected options from the list

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Tapping the Remove icon in a token removes it (2). When the user taps on the input field, the list opens in full screen (3). Tapping the input field sets the focus on it (4) and the mobile device keyboard opens (5). When the user starts typing, the list is filtered (6) using the “starts with per term” approach. The input field only lets the user type characters that match the items in the list.

Left: Multi-combo box with token in the input field; Right: List for selection filtered by a character

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

The following images show how the states of the multi-combo box are styled.

Unselected

Unselected with predefined placeholder

Unselected on hover

In focus

Expanded

Hover highlighting in list

Expanded selection

Expanded multi-selection

Selected items shown as tokens

Warning

Error

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany).

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-combo box. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Message Popover

The message popover (sap.m.MessagePopover) control can handle multiple messages within SAP Fiori. In combination with a message manager, it automatically displays messages that occur after validation points.

With the message concept, we provide a way to centrally manage messages and show them to the user without additional work for the developer.

Message popover

Usage

Use the message popover if:

You want to display multiple messages to the user.
You do not want to interrupt users while they are performing an action.

Responsiveness

Size S (Smartphone)

On smartphones, the message popover is automatically shown in full-screen mode.

Full screen message popover on a smartphone

Layout

Filtering

Initial state

Initially, the filter bar shows all the different types of messages found in the message popover.

General filter

Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success and information), allowing the user to focus on the messages he or she is interested in.

Filter on top of message popover

List

Short description

The short message text provides a simple and helpful short message. It’s the same message as the one attached on the UI control where the issue occurred.

Subtitle

The subtitle provides the chance to give your message an identifier. We recommend that you add the label of the field where the error occurred. Based on the subtitle, the user should be able to identify the corresponding UI control on the UI (for example, the input field in a form).

Navigation to second page

In case there is a long text available, the message popover automatically provides a “chevron” on the right side so that the user is able to navigate to the second page of the message popover, where he or she can read the long text of the message.

Messaging button in full screen layout

Aggregating Messages

If the application development team wants to aggregate messages, they have the chance to fill the counter property of each list item. The app team will have to implement this aggregation on their own as the message popover just provides the counter property.

Messaging button in full screen layout

Detail Page of Message Popover

Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success and information), allowing the user to focus on the messages he or she is interested in.

Messaging button in full screen layout

Messaging Button

If there are no messages to display, you do not need to show a messaging button. The toolbar then only includes the “normal” actions related to the object.

If there are messages to display, the messaging button must look like the example shown in the figure on the right.

Messaging button in toolbar

How to Display the Message Popover

An overview of the different steps needed to display the message popover is provided below. For further information, see message handling.

Behavior and Interaction

When Should the Message Popover Open?

Activation actions

If the user clicks or taps on an activating action (such as Create, Save, or Submit), the message popover should open automatically to inform the user about the active errors on the UI. The message popover provides the user with an overview of the error messages.

Form field validation

If an error occurs (for example, after validating an input field), the message button appears with the number of messages inside. The message popover does not open automatically.

Detailed view

Navigation to the Second Page of the Message Popover

If the message provides a long text from the back-end system, the user is able to navigate to a second page within the message popover. There, the user will typically find more information and helpful message text.

Navigation to second page of the message popover

Navigation to the Relevant Field

Add a navigation link to direct users to the field on the UI that triggered the message. This can be a field in the visible area, a field somewhere else on the same page, or a field on another tab or screen.

For more information about the navigation, see Navigating to the Corresponding Field on the UI in the Message Handling article.

Developer Hint

Set the navigation link with the activeTitlePress event. This allows users to click or tap on the message text in both the first and second page of the message popover.

Navigation to from the message text to a field on the UI

Guidelines

Messaging Overview

No messages to display

If there are no messages to display, you do not need to include a message button in the toolbar.

Highlight the fields

First, highlight the specific field(s) if possible, and change their value state according to the type of message, such as error, warning, or success messages.

Message popover

In addition to the field(s) being highlighted, a button also appears in the toolbar, displaying an icon and the number of messages that have occurred. This number matches the number of fields that have been highlighted. Whenever multiple messages occur, they should be displayed in the message popover, which can be triggered via a button on the left side of the footer toolbar.

Display single messages in a message box

There may also be messages that have to interrupt the user. At present, we are only aware of technical issues such as network errors and connection issues.

Validation Points

No guidelines are currently available regarding data validation. Several cases are possible, which depend on the users, the performance, and the data that needs to be validated. These cases include:

After focusing out
After pressing a key
After clicking or tapping an action, such as Create, Save, or Submit

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Message Handling (guidelines)
Message Box (guidelines)

Implementation

Message Popover (SAPUI5 samples)
Message Popover (SAPUI5 API reference)

Message Popover

The message popover (sap.m.MessagePopover) control can handle multiple messages within SAP Fiori. In combination with a message manager, it automatically displays messages that occur after validation points.

With the message concept, we now provide a way to centrally manage messages and show them to the user without additional work for the developer.

Message popover

Usage

Use the message popover if:

You want to display multiple messages to the user.
You do not want to interrupt users while they are performing an action.

Responsiveness

Size S (Smartphone)

On smartphones, the message popover is automatically shown in full-screen mode.

Full screen message popover on a smartphone

Layout

Filtering

Initial state

Initially, the filter bar shows all the different types of messages found in the message popover.

General filter

Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success and information), allowing the user to focus on the messages he or she is interested in.

Filter on top of message popover

List

Short description

The short message text provides a simple and helpful short message. It’s the same message as the one attached on the UI control where the issue occurred.

Subtitle

The subtitle provides the chance to give your message an identifier. We recommend that you add the label of the field where the error occurred. Based on the subtitle, the user should be able to identify the corresponding UI control on the UI (for example, the input field in a form).

Navigation to second page

In case there is a long text available, the message popover automatically provides a “chevron” on the right side so that the user is able to navigate to the second page of the message popover, where he or she can read the long text of the message.

Messaging button in full screen layout

Aggregating Messages

If the application development team wants to aggregate messages, they have the chance to fill the counter property of each list item. The app team will have to implement this aggregation on their own as the message popover just provides the counter property.

Messaging button in full screen layout

Detail Page of Message Popover

Segmented buttons at the top of the message popover allow the user to filter the messages by type (error, warning, success and information), allowing the user to focus on the messages he or she is interested in.

Messaging button in full screen layout

Messaging Button

If there are no messages to display, you do not need to show a messaging button. The toolbar then only includes the “normal” actions related to the object.

If there are messages to display, the messaging button must look like the example shown in the figure on the right.

Messaging button in toolbar

How to Display the Message Popover

An overview of the different steps needed to display the message popover is provided below. For further information, see message handling.

Behavior and Interaction

When Should the Message Popover Open?

Activation actions

If the user clicks or taps on an activating action (such as Create, Save, or Submit), the message popover should open automatically to inform the user about the active errors on the UI. The message popover provides the user with an overview of the error messages.

Form field validation

If an error occurs (for example, after validating an input field), the message button appears with the number of messages inside. The message popover does not open automatically.

Detailed view

Navigation to the Second Page of the Message Popover

If the message provides a long text from the backend, the user is able to navigate to a second page within the message popover. There, the user will typically find more information and helpful message text.

Navigation to second page of the message popover

Guidelines

Messaging Overview

No messages to display

If there are no messages to display, you do not need to include a message button in the toolbar.

Highlight the fields

First, highlight the specific field(s) if possible, and change their value state according to the type of message, such as error, warning, or success messages.

Message popover

In addition to the field(s) being highlighted, a button also appears in the toolbar, displaying an icon and the number of messages that have occurred. This number matches the number of fields that have been highlighted. Whenever multiple messages occur, they should be displayed in the message popover, which can be triggered via a button on the left side of the footer toolbar.

Display single messages in a message box

There may also be messages that have to interrupt the user. At present, we are only aware of technical issues such as network errors and connection issues.

Validation Points

No guidelines are currently available regarding data validation. Several cases are possible, which depend on the users, the performance, and the data that needs to be validated. These cases include:

After focusing out
After pressing a key
After clicking or tapping an action, such as Create, Save, or Submit

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Message Handling (guidelines)
Message Box (guidelines)

Implementation

Message Popover (SAPUI5 samples)
Message Popover (SAPUI5 API reference)

Network Graph

The network graph displays a large amount of data by highlighting the relationships between individual records. Records are displayed as nodes, and connectors (lines) show the relationships between them. The vivid display of network nodes can highlight non-trivial data discrepancies that would have been previously overlooked.

Sample implementation of a network graph

Usage

Use the network graph if:

You need to display a large amount of data and contextual information. Use cases include material management and supply chains, logistics structures, and value chains.
You want to display complex nonlinear structures, trees, and generic charts (such as organizational charts).
You want to give the data a spatial context.

Do not use the network graph if:

You want to visualize a document flow. Use the Process Flow control instead.
You want to enable editing of displayed data. Note that the network graph is available in read-only display mode.
You need to embed the chart into smaller areas or use it as embedded analytics.

Responsiveness

The network graph is not a responsive control. Only the top bar and dialogs are fully responsive. The graph content, including all the groups, nodes and connectors, keeps the same proportions regardless of the screen size. The proportions are changed only with zoom.

Size S

Size M

Size L

Layout

The network graph is split into a header toolbar that contains all the controls, and the chart.

As an extension to this layout, the control can provide a separate column either on the right or left side of the graph. This column contains a chart map to enable users to navigate to a very large structure more easily. The map displays a smaller version of the graph and the corresponding active area. This column can also be extended by other SAP Fiori controls in order to provide users with enhanced application capabilities.

Schematic visualization of a network graph

Extension panel on the right

Extension panel on the left

Types

The network graph comes with three different layout algorithms:

Generic unordered KLay layout
Column-based layout displayed as either vertical or horizontal swim lanes
Force layout

Each of the layouts can be visualized as a directed or undirected chart. A bi-directional mode is also supported.

Undirected: Data dependency (parent-child) or data flow is not implemented.

Directed: Data dependency is implemented, and different chart orientation can be set. By default, the network graph is oriented left-to-right. Other chart orientations include top-down, center-out, or right-to-left.

Generic unordered KLay

Column-based layout - Vertical

Column-based layout - Horizontal

Force layout

Components

By default, the network graph is split into the header toolbar area and the graph content. Within the graph content, groups, nodes, and connectors are displayed. All of these elements are interactive and display action menus or popups with additional information.

Header Toolbar

A – Title: Provides a short, meaningful summary of the chart contents.
B – Search Field: Standard search component with variant suggestions enabled by default.
C – Legend: Toggles the legend on/off.
D – Zoom In: Zoom in with both mouse wheel or by clicking the icon.
E – Current Zoom Level: Zoom level is expressed as a percentage of the original current chart size.
F – Zoom Out: Zoom out with both mouse wheel or clicking the icon.
G – Fit to Viewport: The network graph automatically applies a zoom level to fit the whole chart into your viewport.
I – Fullscreen: Toggles the full-screen view.

Chart Area

Node

A node represents a single record in the underlying dataset comprising multiple field values. You can use two different shapes to represent a node: a rounded rectangle or a circle.

You click a node to select it. A menu is then displayed, which enables you to expand or collapse the connecting chart structure, display a details dialog, or a links popup.

Connector

A connector represents the relationship between two records and can be displayed as a straight line or a line with arrows.

You click a connector or the surrounding area to call up the details dialog of that specific connector.

Group

A group is a chart element that represents a collection of nodes. A group is envisioned as a slightly larger box containing 1-n nodes. When a group is collapsed it behaves like a node.

Overview of groups

Network graph toolbar

Overview of nodes

Overview of connectors

Warning

Following features have not yet been integrated into this version and will come in the next release(s):

Icons for rounded rectangular nodes
Semantically colored values with different font-weight
New visuals for Group statuses
Starting Node visualization

Behavior and Interaction

Navigation and Zoom

A user can navigate around the entire network graph by holding down the left mouse button and dragging the mouse. By dragging the graph, the user changes the active area of the available graph map extension. Clicking or dragging the selected area in the graph map extension changes the focus area of the network graph.

To zoom in or out, the user can use the mouse wheel, pinch open or pinch close on the touch devices, or click the respective buttons on the top bar. Each of these actions changes the number label, located between the zoom in and zoom out icon buttons, and indicates the current zoom level.

Fit to Viewport automatically adjusts the zoom level to fit the entire network graph into the user’s viewport.

Component Interaction

Clicking a node displays a menu, which provides the users with the option to collapse the following chart structure, display the details dialog, or display the links popup.

Clicking a connector or the area surrounding it calls up the connector’s details dialog.

For group interactions, clicking the display details icon button nested in the group heading calls up the group’s details dialog (it also contains the list of the nodes included in the group).

Collapsed Structure Indication

In more complex structures, many structures may be hidden within the graph. To indicate collapsed structures, we use a visual indication to represent collapsed structures following the node and collapsed structures within a group.

Partially Expanded Indication

In a directed graph, Expand/Collapse applies only to the subtree directly connected to the selected node. Each node supports a three-state action button for expanding or collapsing:

Fully expanded
Partially expanded
Collapsed

When a user clicks the action button in a fully expanded state, the affected node’s subtree is collapsed, and the action button of that node is indicated as collapsed. All other nodes sharing parts of the subtree with this node and will then be indicated as partially expanded.

When a user clicks the action button in a partially expanded state, the affected node’s subtree is collapsed, and the action button of that node is indicated as collapsed. All other nodes affected by this action are indicated as partially expanded.

When a user clicks the action button in a collapsed state, the affected node’s subtree is expanded and the action button of that node is indicated as expanded.

Node interaction showing 'More' menu and 'Details' popup

Visual indication of collapsed structure following the node or group

Indication of collapsed, expanded, and partially expanded structures

Styles

Each node can be visualized with a circle or rounded rectangle shape. These two shapes can be combined inside one graph to provide users with deeper semantic meanings: for example, circular nodes represent customers, whereas rounded rectangles represent suppliers.

Semantic meanings can be assigned to line styles for connectors, and semantic colors can be assigned to both nodes and connectors.

Node Types

As mentioned above, there are two default node shapes: circle or rounded rectangle. In addition, these node shapes have different label and title (icon) positioning.

If needed, the application owner can also define the number of the allowed lines for a node title.

Connector Types

You can give connectors semantic meaning by assigning them semantic colors or different line types. You can also use both semantic colors and different line types to provide connectors with a deeper meaning.

Connector types and their semantics

Guidelines

In applications, embed the network graph only within components that use the whole canvas area, such as the tab container on the object page. Do not embed the network graph in smaller containers, such as panels, headers, tables, forms, and dialogs.

The network graph is not a substitute for a Process Flow. For more details, see the Usage section at the top of this article.

Keep the amount of information inside each node to a minimum. You can reveal more information via the details popover.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Popover (Guidelines)
Toolbar (Guidelines)

Implementation

Network Graph (SAPUI5 samples)
Network Graph (SAPUI5 API reference)

Bullet Chart

The bullet chart is used to compare primary and secondary (comparison) values.

Encoded Values

Primary Values

Frequently used for actual values, primary values can also be used for any type of value that you want to compare to the secondary/comparison value.

Secondary/Comparison Values

Frequently used for target and plan values, comparison values can also be used to compare the primary value with any other value. There are use cases where the comparison value is used to express a forecast, a competitor, or a specific year.

Additional Values

The bullet chart can also express an additional value so long as it’s directly related to the primary value.

Orientation

The bullet chart can be orientated horizontally or vertically. It’s best to orientate it vertically for time series.

Horizontal bullet chart

Vertical bullet chart

Color Palette

If nothing is customised, the bullet chart will automatically use colors from the qualitative palette.

However, it is also possible to customize the colors (for example, if you want to differentiate between categories). For more information, check out the article on bullet chart colors.

SAP Fiori chart palettes

Selection and Popover

Unlike other charts, when the user clicks on a bullet, all the associated values are displayed in the popover – primary value, comparison value along with additional value, projected value, and qualitative ranges (if used). The popover can also be customized to display other information and actions if you wish.

Popover

Legend

As with all other charts, when you customize the colors, the text of each legend item must also be manually maintained because the chart component cannot guess the meaning of each color.

For more information, see legend.

Legend

Negative Values

The horizontal and the vertical bullet charts can support negative values. Negative values can be applied to both the primary and the secondary (comparison) values.

Horizontal bullet chart with negative values

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Chart (guidelines)
Bullet Chart – Color Use for Primary Values (guidelines)

Implementation

Vertical Bullet Chart (SAPUI5 samples)
Horizontal Bullet Chart (SAPUI5 samples)
Bullet Chart with Negative Values (SAPUI5 samples)
Popover (SAPUI5 samples)

Stacked Bar Micro Chart

The stacked bar micro chart is designed to be embedded into a list, table, or object page header as a way to represent related values atop one another in order to visualize the single values as part of a whole. These values can be displayed in two different ways:

Percentage compared to 100%

Use percentage values if your goal is to see each value in the composition as a percentage of the whole. In this case, the sum of the bars is always 100%.

Percentage values (without labels)

Values compared to a maximum value

Use this option in a list or table if your goal is to compare the sum of the values to a maximum value (for example, the maximum of all data shown in the list or table), whilst still displaying the relative value of each to its local maximum.

Absolute values (without labels)

Please note: The stacked bar micro chart does not support negative values.

Usage

Use the stacked bar micro chart if:

You want to visualize a part-to-whole relationship embedded in a list or table, with all the features described above.

Chart embedded in a table - Percentage values (without labels)

Chart embedded in a table - Absolute values (without labels)

You want to visualize a part-to-whole relationship in an object page header, with all the features described above.

Also consider using a Harvey Ball micro chart as an alternative visualization for a part-to-whole relationship.

Chart embedded in an object header - Percentage values (with labels)

Chart embedded in an object header - Absolute values (with labels)

Do not use the stacked bar micro chart if:

You want to visualize a part-to-whole relationship on a SAP Fiori tile. The stacked bar micro chart is not designed to be embedded into an SAP Fiori tile and is therefore not supported. Consider using a Harvey Ball micro chart instead.

Responsiveness

The stacked bar micro chart is fully responsive. The size adjusts dynamically based on the dimensions of the parent container. In addition, there are also four fixed sizes – L, M, S and XS. Each fixed size is a snapshot of the fully responsive micro chart for specific dimensions.

Stacked bar micro chart - Size L

Stacked bar micro chart - Size M

Stacked bar micro chart - Size S

Stacked bar micro chart - Size XS

You can use the smallest XS size to embed the stacked bar micro chart in the table cells of the grid table, analytical table, or tree table (also in condensed mode). Left-align the stacked bar micro chart in the table cell.

Stacked bar micro chart in XS size in the grid table

Maximum and Minimum Sizes

The stacked bar micro chart can have the following dimensions:

Maximum width: 320 px
Minimum width: 64 px.

Maximum height: 94 px
Minimum height: 18 px.

If the label is too long to fit inside the bar, it is hidden. With the minimum chart height, the labels are not shown.

Components

Maximum Value

The chart is scaled relative to the maximum value. This means if a maximum value (maxValue) is set, then the width of the stacked chart represents the maximum value and each value within the chart is scaled relative to this maximum.

If the maximum value is not set, then the width of the chart represents 100% and each value is displayed as a relative percentage.

Precision

By setting a specific value for the precision, an application developer can influence rounding calculations by defining how many digits are displayed. By default this value is 1.

Display Value

By default, the control displays percentage values on the bars. However, application developers can also set a display property to show absolute values, or to show only bars (by entering a blank space).

Color

An application developer can set any color for the chart either by using names of semantic colors, or by using names from the qualitative palette (sapUiChartPaletteQualitativeHue1…11).

Please note: A legend is currently not available for the stacked bar micro chart. Since the use of multiple colors is not self-explanatory, we highly recommend using semantic colors and an explanatory title for the chart.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Micro Chart (guidelines)
Color Palette (guidelines)
Chart Types (guidelines)

Implementation

Stacked Bar Micro Chart (SAPUI5 samples)
Stacked Bar Micro Chart (SAPUI5 API reference)

Micro Chart

Micro charts help you visualize a small number of data points in a small, non-interactive way. They can be embedded in tiles, SAP Smart Business drilldowns, and any SAPUI5 container (such as SAPUI5 tables).

Usage

Use the micro chart if:

You want to provide tracking at a glance.
You want to display changes in the data in an easy and condensed way.

Do not use the micro chart if:

You are looking for interactive analytics. Use the analytical card instead.
You want to display extensive data. Use the vizFrame chart instead.

Responsiveness

All micro charts are fully responsive. The size of the control adapts automatically to the size of the parent container and does not have a defined width or height.

Types

The following micro charts are currently available:

Area Micro Chart

Bullet Micro Chart

Column Micro Chart

Comparison Micro Chart

Delta Micro Chart

Harvey Ball Micro Chart

Line Micro Chart

Radial Micro Chart

Stacked Bar Micro Chart

Choosing the Correct Chart Type

Charts are used to visually represent the relationships between numeric values. In order to choose the correct chart type, it’s important to define the type of relationship you want to illustrate.

Ranking

If you want to rank items from highest to lowest, or vice versa, we recommend using the comparison (bar) micro chart. For time-based categories, the column micro chart is more appropriate.

Micro charts for ranking

Comparison

To compare items that don’t have a particular order, you can use the comparison micro chart (offering category and value labels for each part) or the column micro chart.

Sometimes it can also be useful to show when a certain value reaches or exceeds a reference point (for example, when an actual value is compared to a target or forecast). In such cases, use a bullet micro chart. Keep in mind that the bullet micro chart shows data points for given points in time. Do not use it to show a time series.

To compare value totals within and across different categories, you can use the stacked bar micro chart.

Micro charts for comparison

Variation over Time

By convention, time is represented horizontally from left to right which means it’s best to use the horizontal axis to represent the time in chart visualizations.

To show changes in measures over time, you can use the line micro chart, the column micro chart, and the area micro chart. The exact chart type depends on the type of change you want to visualize.

If you want to emphasize the trend over time, use the area micro chart (which provides information for actual and target values, visualized and compared to threshold areas) or the line micro chart. If you want to emphasize the values themselves, use the column micro chart.

Micro charts for variation over time

Part to Whole

You can use several chart types that depict the contribution of individual values to a whole.

The typical chart for visualizing part of a whole is the Harvey ball micro chart. This is most suitable if you want to display a single value compared to its total. To show a single percentage value, use the radial micro chart.

The stacked bar micro chart works best for visualizing different values as part of one whole; its bars are shown next to each other. The comparison micro chart is better if you want to compare parts to each other and display category labels and value labels associated with each part.

Micro charts for part to whole

Deviation

These chart types visualize the difference or variance between two values (or two sets of values).

To show a time-related deviation between sets of values, use the area micro chart (for example, to show the difference between actual expenses and target expenses), or the line micro chart.

If you want to emphasize the deviating values, use the column micro chart (suitable for showing variances), or the comparison micro chart (offering category and value labels).

The bullet micro chart shows the difference between two values (actual and target) or three values (actual, target, and forecast) at a given point in time.

The delta micro chart helps to visualize a delta value (difference) between two main key figures, which can be time-related or category-based.

Micro charts for deviation

Distribution

To visualize how values are distributed within a set, we recommend using the column micro chart or the comparison micro chart (offering category and value labels). The stacked bar micro chart shows the distribution of values as part of a whole.

If you want to emphasize the shape of the distribution over time, use the line micro chart.

Micro charts for distribution

Behavior and Interaction

Clicking/Tapping (Optional)

The micro charts include one interaction: a click event that can be switched on or off.

“No data” Text

When data is missing, a white rectangular placeholder with the text “No data” is shown instead of the chart. The size of the placeholder depends on the size of the chart. No labels and tooltips are shown. The “No data” placeholder can be focused, but it’s not possible to attach a click event to it.

Area micro chart without data

Comparison micro chart without data

Line micro chart without data

Bullet micro chart without data

Delta micro chart without data

Radial micro chart without data

Column micro chart without data

Harvey Ball micro chart without data

Stacked bar micro chart without data

Guidelines

Truncation

Never truncate numeric labels, as this could be misleading for the user. If there is not enough space for the label, hide it.

“No data” Text

If the micro chart is placed in the cell of a table and there is no data for the chart, leave the cell blank (empty).

Micro charts without data in table cells

If the chart is used in the micro chart facet of the object page header and data is missing, make sure the footer of the facet is removed as well if it doesn’t add any value for the user.

Micro charts without data in the object page header

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Color Palettes (guidelines)
VizFrame chart Types (guidelines)
Area Micro Chart (guidelines)
Bullet Micro Chart (guidelines)
Column Micro Chart (guidelines)
Comparison Micro Chart (guidelines)
Delta Micro Chart (guidelines)
Harvey Ball Micro Chart (guidelines)
Line Micro Chart (guidelines)
Radial Micro Chart (guidelines)
Stacked Bar Micro Chart (guidelines)

Implementation

Area Micro Chart (SAPUI5 samples)
Bullet Micro Chart (SAPUI5 samples)
Column Micro Chart (SAPUI5 samples)
Comparison Micro Chart (SAPUI5 samples)
Delta Micro Chart (SAPUI5 samples)
Harvey Ball Micro Chart (SAPUI5 samples)
Line Micro Chart (SAPUI5 samples)
Radial Micro Chart (SAPUI5 samples)
Stacked Bar Micro Chart (SAPUI5 samples)

Comparison Micro Chart

The comparison micro chart is a bar chart. It compares entries in a top N list. Depending on the width of the parent container, it can have two different layouts: normal view and wide view. You can use either the semantic chart palette or the qualitative chart palette.

Comparison micro charts in normal view

Comparison micro charts in wide view

Usage

The comparison micro chart can be embedded into a table, list, tile, or header.

Responsiveness

The comparison micro chart is fully responsive. The size adjusts dynamically based on the dimensions of the parent container. In addition, there are also four fixed sizes – L, M, S and XS. Each fixed size is a snapshot of the fully responsive micro chart for specific dimensions.

Comparison micro chart with 3 bars - Size L

Comparison micro chart with 3 bars - Size M

Comparison micro chart with 3 bars - Size S

Comparison micro chart with 3 bars - Size XS

You can use the smallest XS size to embed the comparison micro chart in the table cells of the grid table, analytical table, or tree table (also in condensed mode). Left-align the comparison micro chart in the table cell.

Comparison micro chart with 3 bars in XS size in the grid table

Maximum and Minimum Sizes

The comparison micro chart can have a maximum width of 320 px. The minimum width is 64 px.

In normal view, the labels for the bars are positioned on top of each bar.

If the chart width exceeds 192 px, the chart goes into wide view and the labels for the bars are positioned on both sides of the bar.

If the chart width is 96 px or less, the labels are hidden.

Comparison micro chart with 3 bars and labels on both sides

Comparison micro chart with 3 bars and labels above

Comparison micro chart with 3 bars without labels

Guidelines

Use a maximum of 12 bars in a single comparison micro chart.
We strongly recommended using at least 2 bars in a single chart to visualize a comparison.
When embedding comparison charts in tables, use the same number of bars for all the charts in a given table column. This makes the data comparable and avoids misleading the user. Use a suitable column header to describe the embedded charts.

Do

Use comparison charts with the same number of bars in a table column

Don't

Do not use comparison charts with different numbers of bars in the same table column

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Micro Chart (guidelines)
Color Palette (guidelines)
Chart Types (guidelines)

Implementation

Comparison Micro Chart (SAPUI5 samples)
Comparison Micro Chart (SAPUI5 API reference)

Bullet Micro Chart

A bullet chart is a variation of a bar graph originally developed by Stephen Few and adapted by SAP Fiori in order to fulfill additional requirements. Much like the traditional thermometer charts and progress bars found in many dashboards, the bullet chart serves as a replacement for dashboard gauges and meters.

The bullet chart features a single, primary measure (for example, current year-to-date revenue). It compares that measure to one or more other measures to enrich its meaning (for example, compared to a target), and displays it in the context of qualitative ranges of performance, such as poor, satisfactory, and good.

Bullet micro chart without forecast

Bullet micro chart with forecast

Bullet micro chart with only delta value shown

The actual value is shown as a colored horizontal bar, the target value as a vertical line (marker), and the thresholds as indicators above and below the bar. The actual and target values can have a label.

Only semantic colors (good, critical, bad, neutral) can be used for the actual value.

The forecast is shown as a bar with a lighter tint of the same color as the actual value in the background.

Based on the data points you want to show, choose one of the following visualizations:

Actual value vs. target value
Actual value vs. target value with forecast
The delta between the actual value and the target value. For this option, the delta is shown as a bar starting or ending at the target marker.

Usage

The bullet micro chart can be embedded into a table, list, tile, and header.

Responsiveness

The bullet micro chart is fully responsive. The size adjusts dynamically based on the dimensions of the parent container. In addition, there are also four fixed sizes – L, M, S and XS. Each fixed size is a snapshot of the fully responsive micro chart for specific dimensions.

Bullet micro chart - Size L

Bullet micro chart - Size M

Bullet micro chart - Size S

Bullet micro chart - Size XS

You can use the smallest XS size to embed the bullet micro chart in the table cells of the grid table, analytical table, or tree table (also in condensed mode). Left-align the bullet micro chart in the table cell.

Bullet micro chart in size XS in a grid table

Maximum and Minimum Sizes

The bullet micro chart can have the following dimensions:

Maximum width: 320 px
Minimum width: 64 px.

Maximum height: 94 px
Minimum height: 18 px.

If the chart height is less than 56 px, the labels are hidden.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Micro Chart (guidelines)
Color Palette (guidelines)
Chart Types (guidelines)

Implementation

Bullet Micro Chart (SAPUI5 samples)
Bullet Micro Chart (SAPUI5 API reference)

Object Display Components

There are four types of object display components: object status, object identifier, object number, and object marker. Each one is connected to an object and displays a certain type of information (status, identifier, number, marker).

Object Status

The object status is a short text that represents the semantic status of an object. It has a semantic color and an optional icon. Typically, the object status is used in the dynamic page header and as a status attribute of a line item in a table.

Object Identifier

The object identifier is a short text that represents the key identifier of an object.

You can find the object identifier in a table as an identifier of the line item.

Object Number

The object number is a short text that represents the numeric (key) attribute of an object and its unit. The number has a semantic color, and the unit inherits the same color from its number. The number can be emphasized (default setting) when it is used for the key attribute, and non-emphasized when it is used for any other numeric attribute of the item.

The object number is typically used to indicate the key attribute of an object in the dynamic page header, or as an attribute of a line item in a table.

Object Marker

The object marker indicates the technical status of an object. It is enabled for the dynamic page layout, snapping header, object page header, upload collection, and object list item.

The technical status can be represented as and icon, with an icon and text, or as text only, depending on the screen size. See the Guidelines section below to find out when to use each visibility option.

Currently, the following technical statuses can be visualized by the object marker:

Flag
Favorite
Editing Status (Draft, Locked, Unsaved Changes)
The editing status is part of the draft handling concept.

Usage

Use the object status if:

You need to display the semantic status of an object: negative (property: error), critical (property: warning), positive (property: success), or neutral (property: none).

Use the object number if:

You want to display the key attribute of an object. In this case, keep the default emphasized setting (property: emphasized).
You need to display one or more numeric attributes of an object that, for example, you want to compare (property: emphasized set to “false”).

Use the object identifier if:

You want to indicate the key identifier of the object.

Use the object marker if:

You want to display the technical state of an object (locked, draft, unsaved changes, favorite, flagged). If you want to display the status of the object in the business lifecycle, consider using the object status display component instead.
You need to show that the current object instance is locked by another user.

Do not use an object display components if:

You want to display system messages.
They are for decoration purposes only.

Responsiveness

The object status wraps if it is longer than the available screen width.
The object identifier text wraps if the size of the screen becomes too small to display the entire text on one line.
The object number does not wrap or truncate. For large numbers, you need to consider using the appropriate formatting.
The object marker does not wrap or truncate. It comes with different display options. Depending on the screen size and the selected visibility option, the object marker behaves as follows:
- Size L/M:
  - If the visibility is set to IconAndText, both are displayed.
  - If the visibility is set to IconOnly, only the icon is displayed.
  - If the visibility is set to Text, only the text is displayed.
- Size S:
  - If the visibility is set to IconAndText, only the icon is displayed.
  - If the visibility is set to Icon, only the icon is displayed.
  - If the visibility is set to Text, only the text is displayed.

For more information about the responsive behavior of text in general, see Wrapping and Truncating Text.

Components

Object Status

The object status consists of the following:

A semantically colored text indicating the severity (property: text).
An optional icon (property: icon).
An optional link (property: active). If the object status is used as a link, a hover effect is shown on non-touch devices.
If the object status is shown using a combination of icon and text, there is no hover effect for the icon.

We recommend using the semantically colored text-only option. For more information about the meaning of the colors, see How to Use Semantic Colors.

Text-only object status

Object status with icon, text, and link in hover state

Object Identifier

The object identifier has the following properties:

A title text (property: title)

Object identifier with title only

An optional additional descriptive text (property: text)

Object identifier with title and subtitle

The title can be set to active. In this case, it looks like a link and can fire an event (property: titleActive).

Actionable object identifier

Both texts wrap if the space available is insufficient for them to each fit on one line.

Object identifier with wrapping text

Object Number

The object number consists of the following:

A colored text (property: number), which can be set to non-emphasized when used in the content area (property: emphasized).
Semantics to indicate the status: negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none). For more information about the meaning of the colors, see How to Use Semantic Colors.
An optional unit (property: unit).

Emphasized object numbers

Object numbers

Object Marker

The object marker comes with the following characteristics:

Icon only (visibility: IconOnly)
Text only (visibility: TextOnly)
Icon and text (visibility: IconAndText)
Interactive
Non-interactive

The object marker is able to fire an an event when it is pressed (interactive). If the control is interactive and displayed as an icon with text, the icon and text are one click area.

Draft

Unsaved changes

Locked

Favorite

Flagged

Guidelines

General

The object status and object number can make use of semantic colors. Check out when and how to use the semantic colors.

Object Status

General

Use semantic text only, and avoid using it with an icon.
Use the following semantics to indicate the status/severity: negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).

Positive object status

Provide a link for the object status if the user needs additional information about the status (for example, using a popover).

Critical object status during hover state

Only use icons if they are unambiguous and easily understood (such as a padlock for locked items). If you feel that your icon needs a descriptive text to be understood, use text only.

Widely used icon for warning

Tables

Always left-align the object status in a table.
Exception (responsive table only): If status information is displayed as secondary information in a column, the status should follow the alignment of the primary information.

Apply the following rules for sorting tables by status:

Ascending: Sort status information from positive to negative, with neutral last.
Descending: Sort status information from negative to positive, with neutral first.

Object status sorted ascending, with neutral status last

Object status sorted descending, with neutral status first

Ascending with different values per severity level: Sort status information from positive to negative, with neutral last. Sort different values within a severity level (semantic color) alphabetically.
Descending with different values per severity level: Sort status information from negative to positive, with neutral first. Sort different values within a severity level (semantic color) alphabetically.

Object status sorted ascending and alphabetically, from positive to negative with neutral last

Object status sorted descending and alphabetically, from negative to positive with neutral first

Object Identifier

The object identifier should be easily readable (preferably the display text and not the ID). If the ID is necessary to distinguish between items that use the same title, it should appear in brackets, such as Product ABC (1234567). The decision to include the ID in the text property can also depend on how long you expect the text to be.
The object identifier can also be shown as a link. In this case, the event opens the quick view of the object.

Object Number

If the object number is the key attribute of the object inside the content area, emphasize the number when it is used as a line item status in a table.
The object number can also be used to visualize other semantic numeric attributes. In this case, they are not emphasized unless they are the key attribute, such as a sum.

Object number used as a semantic attribute (weight) and as a key attribute (price)

Object Marker

An object can have multiple technical statuses at the same time. However, because the editing statuses are mutually exclusive, users will see a maximum of 3 technical statuses for an object: Flag, Favorite, and one Editing Status. The app developer is responsible for the technical statuses.

Every technical status has a default visualization that can be changed by the app developer depending on the usage context. Also see How to Display the Editing Status in the Draft Handling article.

Flag and Favorite are usually displayed as icons on all screen sizes. For more information, see Flag and Favorite.

The default behavior for the editing status is as follows:

Size L/M:

Locked and Unsaved Changes are displayed as icon and text, while Draft is displayed as text.
Flag and Favorite are displayed as icons.

Size S:

Locked and Unsaved Changes are displayed as icons, while Draft is displayed as text.
Flag and Favorite are displayed as icons.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

How to Use Semantic Colors (guidelines)
Wrapping and Truncating Text (guidelines)
Flag and Favorite (guidelines)
Responsible Table (guidelines)

Implementation

Object Identifier (SAPUI5 samples)
Object Identifier (SAPUI5 API reference)
Object Marker (SAPUI5 samples)
Object Marker (SAPUI5 API reference)
Object Number (SAPUI5 samples)
Object Number (SAPUI5 API reference)
Object Status (SAPUI5 samples)
Object Status (SAPUI5 API reference)

Text

The text control is used to display text. It generally contains the text that developers want apps to display (property: text).

Text used within a form

Usage

Use the text control if you want to display text inside a form, table, or any other content area. Do not use the text control if you need a label, or vice versa.

Responsiveness

The text control is fully adaptive to all screen sizes. You can also set a specific width and overwrite the default value. The resizing behavior depends on the settings that the apps use for the text.

Properties

You can define whether the text should wrap or directly truncate (property: wrapping).

You can also define how often the text should wrap before it truncates (property: maxLines).

For more information about the responsive behavior of text, see Wrapping and Truncating Text.

Note: The truncation indicator for multiple lines depends on the browser line clamping support. For browsers that support it, this will be shown as ellipsis (…), whereas in other browsers, the overflowing text will just be cut off.

Text – Maximum line examples

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Label (guidelines)
Wrapping and Truncating Text (guidelines)

Implementation

Text (SAPUI5 samples)
Text (SAPUI5 API reference)

Link

A link (also known as hyperlink) is a clickable text element. The link control is used for navigation, but can also trigger an event. Links are visualized to stand out from standard, non-clickable text.

Usage

Use a link if:

The control you are using does not support other navigation options.
You want to reference an object (for example, from a form or table).
Note: Use the quick view control to show the object details (sap.m.QuickView).

Do not use a link if:

The link text is the key identifier of an object. In this case, use an actionable object identifier instead.
You could use a button to trigger the action instead. If you want the button to look like a link, you can use a transparent button.

Responsiveness

A link can react to insufficient room in two different ways:

By default, the text is truncated to fit the available screen real estate.
If you enable wrapping, the link uses more lines instead of truncating the text (property: wrapping).

For more information and guidelines on the responsive behavior of text, see Wrapping and Truncating Text.

Link – Wrapping and truncation

Link – Wrapping and truncation (hover)

Behavior and Interaction

Triggering an Event

The purpose of a link is to trigger navigation or an event. The action is triggered when the user clicks or taps the link. For navigation links, you can specify a target to define where the linked content should open (property: target).

Hovering

When the mouse pointer is positioned over a link, the user gets additional visual feedback (underlining) to emphasize that the text is a clickable link.

Hovering over the link with the mouse

Disabled State

A link can have a disabled state to indicate that it is currently not clickable. Only disable a link if the user has other options for accessing the function behind the deactivated link.

Disabled links

Styles

Besides the standard link visualization, there are two more styles: subtle and emphasized.

Subtle

You can use subtle links to distinguish between important and less important (subtle) links (property: subtle). This allows you to improve the visual hierarchy in large data lists.

Do not use subtle links for any other use cases.

Emphasized

If the standard link visualization is not sufficient to attract the user’s attention, you can highlight the link (property: emphasized).

Links shown in different styles

Links shown in different styles when hovering

Guidelines

Use a meaningful link text that indicates what will happen when the user clicks the link (for example, Open Sales Order). Avoid texts such as Click Here or Link, as these do not meet accessibility standards.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Button (guidelines)
Object Display Components (guidelines)
Wrapping and Truncating Text (guidelines)

Implementation

Link (SAPUI5 samples)
Button (SAPUI5 samples)
Object Identifier (SAPUI5 samples)
Link (SAPUI5 API reference)
Button (SAPUI5 API reference)
Object Identifier (SAPUI5 API reference)

Label

A label is the name or title of a control or group of related controls.

Label "Name" in a form

Usage

Use the label control if:

You need a label for a control. We recommend that you always use labels for form controls.

Do not use the label control if:

You want to insert a heading in the column header of a table.
You want to use it as an alternative for the text control. Do not use the label control to display the data (for example, in display-only forms).

Types

There are two types of labels:

Required
Optional

To indicate that a field is required, set the required property to true. An asterisk is then added automatically in front of the label.

Required label in an editable environment (horizontal layout)

Result of a required label in a display-only environment

Optional label in an editable environment (vertical layout)

Result of an optional label in a display-only environment

Styles

For better differentiation of labels and values, labels are displayed differently in a display-only environment than in an editable environment.

Wrapping

Automatic wrap only applies to labels within forms to avoid truncation.

Do not use wrapping to enable long labels. Instead, keep your labels short: a label is not a help text. It must be meaningful, succinct, short, and descriptive. For more information about the responsive behavior of text, see Wrapping and Truncating Text.

Developer Hint

The boolean wrapping property for the sap.m.Label control determines whether or not the text wraps .

Note: Only use this property in forms.

Wrapping label

Guidelines

Always use a label for form controls.
Always set the vertical alignment for labels that display outside a form and flex box (property: VAlign). You can set the vertical alignment in tables and object page header facets, for example.
Use title case for labels.
Do not use a placeholder (input prompt) instead of a label.
Do not use bold labels.
A label is not a help text: it must be meaningful, succinct, short, and descriptive.

Exceptions

The layout can sometimes be simplified by using a placeholder instead of the label control. This exception can be applied in the following cases:

When the form pattern is easily understood, such as on a login screen. Since this screen consists of only two input controls (User Name and Password), the labels do not have to be used.
When the form is extremely small and has fewer than three input fields. This can be the case for messages or small feedback forms.
In search fields. For more information, see Search.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Form (guidelines)
Text (guidelines)
Wrapping and Truncating Text (guidelines)

Implementation

Label (SAPUI5 samples)
Label (SAPUI5 API reference)

Calculation Builder

The calculation builder can be used to create complex expressions that combine numeric constants and variables with arithmetic and logical operators. The expressions can be entered using a visual editor or a text editor with three available layout options.

Usage

Use the calculation builder if:

You need to create or edit complex arithmetic expressions.
You need to define or modify business KPIs.
You need to keep the dependencies of the underlying calculations and to be able to expand them.

Responsiveness

The calculation builder is fully responsive, and uses 100% of the width provided by the container in which it is embedded. For size S, it is mandatory to use 100% of the page width.

Depending on the available width, the calculation content is broken into separate lines in order to keep the native vertical scrolling for the whole page.

Calculation Builder - Size M

Calculation builder - Size L

Calculation builder - Size S

Layout

The calculation builder provides three different types of layout:

By default, the header toolbar and both the visual and textual editors are displayed. The header toolbar includes a toggle button for hiding or displaying the textual editor.
Only the header toolbar and the textual editor are displayed, making the calculation builder a text-only control.
The header toolbar and visual editor are displayed. The header toolbar includes buttons for arithmetic and logical operators, as well as variables. The toolbar buttons show the user which operations and variables are supported.

Header toolbar + visual editor + textual editor (default)

Header toolbar + textual editor only

Header toolbar (with operators and variables) + visual editor

Layout Examples

The following examples show how the different layout types appear on the UI.

Default layout

Header toolbar with expression operators and textual editor

Header toolbar with textual editor only

Components

The calculation builder can include thee components:

A header toolbar
A visual editor
A textual editor

Header Toolbar

A – Title: Provides a short and meaningful summary of the expression.

B – Textual Editor Toggle: Enables the user to hide the Expression Output section and work with the visual editor only

C – Expand All Variables: Allows the user to expand all the variables included in the expression and see all the underlying calculations used to compose the variable.

D – Full Screen: Toggles the full screen view.

Visual Editor

A – Functions: Functions require brackets. The initial bracket is automatically inserted after the function name. Only a limited subset of functions is supported by default. However, you can define any custom function you need using the API.

B – Variables: A custom set of available KPIs, such as revenue, assets, or expenses. KPIs are predefined by each application.

C – Constants: Enables user to type the values directly as standalone constants or as part of a function.

D – Operators: Arithmetic, logical, and comparison operators are available.

E – New Element: The default button of each expression triggers a dialog to add a new function, variable, operator, or constant.

Textual Editor

The textual editor contains a plain text representation of the expression entered in the visual editor.

If the user copies an arithmetic expression from an external application and pastes it to the textual editor, the expression displayed in the visual editor will be updated automatically. The same applies the other way round: if the user enters an expression using the visual editor, the textual editor gets updated, which can be used to copy the expression to an external application.

Header toolbar

Visual editor

Textual editor

Behavior and Interaction

Inserting New Calculation Elements

The user has two options for adding an operator, constant, variable, or function to an expression:

By clicking the New Element button
By typing it directly into the textual editor field, which makes it appear in the visual editor as well.

The New Element button triggers a dialog with the selection of all available calculation elements.

Developer Hint

You can customize the calculation elements available to your users, add custom functions, load a specific list of variables, or disable any of the default calculation elements.

Selecting a constant

'New Element' dialog

Selecting a variable

Selecting a function

Selecting an operator

Expanding Variables

There are two ways a user can expand a variable to see the underlying structure of the variable.

Expand an individual variable by clicking the Expand Variable button.
Expand all variables by clicking the Expand All Variables button in the header toolbar.

In both cases, a confirmation message is displayed warning the user that this action is irreversible and variables cannot be collapsed back.

When a variable is expanded, the user can also remove the dependency on the original variable, if needed.

Warning

Expanding a variable is currently an irreversible action, and the dependency on the original variable can only be restored if you insert the original variable again as a new calculation element.

Selecting a variable to expand

Confirming the variable expansion

Guidelines

When the default layout is used, displaying both the visual and textual editors, we advise against adding the editor buttons for operators, constants, functions, and variables to the header toolbar.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Toolbar (Guidelines)
Popover (Guidelines)
Button (Guidelines)

Implementation

Calculation Builder (SAPUI5 samples)
Calculation Builder (SAPUI5 API Reference)

Table Toolbar

The table toolbar always appears above the table and has a transparent background. The control is used for key actions that impact the entire table.

Usage

Use the table toolbar if:

There are multiple objects on your page and you need to edit only the table.
You want to show actions as close to their corresponding controls as possible.
You need a title for your table.

Do not use the table toolbar if:

You are using single selection and only one or two actions. In this case, place the actions on each line.

Responsiveness

To enable responsiveness, use the OverflowToolbar control. For more information, please refer to the corresponding section in the toolbar overview article.

Components

All of the components are optional. The table toolbar can contain the following actions:

App-specific actions
Generic actions

The following actions count as generic:

Title
Variant management
Switch
Search
Edit
View switch
Create (for new items)
Add (for existing items)
Sort, Filter, and Group (view settings)
Personalize
Export to spreadsheet
Print
Overflow

Example of possible components

Behavior and Interaction

App-Specific Actions

If needed, the app team can define their own actions for the app. In this case, the text buttons should contain a short, unambiguous text that explains what action the button performs. A button text is usually a single-word verb (for example, Share). Note that translated UIs may increase the length of the text string.

Only use icon buttons if you are sure that the user will be able to interpret the meaning of the icon easily and without the aid of a tooltip. Use standard and easily recognizable icons, such as a paper clip for an attachment.

Table toolbar with app-specific icon buttons

Title (Generic)

A title provides a short, meaningful summary of the content, mostly by using a single word. The title bar is a toolbar property that supports consistently-sized text and titles with the same height in cozy and compact form factors.

Consider the following when using a title:

Use the sap.m.Title control.
The toolbar height must be set to 3 rem.
The title must have the label class sapMH4Fontsize.

Use a table title if you need the table toolbar, and if the title of the table is not indicated in the surrounding area. To avoid repeating text, feel free to use generic text as a table title, such as Items. Note that the title becomes truncated if there is not enough space.

Title in the table toolbar

Variant Management (Generic)

Variants store settings that have been defined, for example, for layout, column visibility, sorting, and grouping. The variant management control enables the user to load, save, and change variants.

In the context of tables, the variant management control is used to save, manage, and load table settings which include layout, column visibility, sorting, and grouping.

For this, the variant management control can be used independently of the filter settings.

Always place this control in the table toolbar next to the title.

If you place the variant management control inside a toolbar, you need to apply the following styles:

The toolbar height must be set to 3 rem.
The title must have the class sapMH4Fontsize.

The examples below show where to place this control:

Variant in the table toolbar

Title and Variant Management (Generic)

In exceptional cases, both the title and variant management have to be used. However, we do not recommend this because it results in a crowded toolbar and problems with responsiveness may occur. Variant management alone is generally sufficient.

The title and variant management are both left-aligned. The title is placed first, followed by a separator and the variant management.

Title with variant management

Content Switch (Generic)

When apps need to switch between different content in a table, use a select control (also known as a dropdown) or a segmented button. The select control and the segmented button are displayed left-aligned in the table toolbar and allow the user to show different views.

These views could be very specific. For example, All, Mine, and Others. However, you should ensure that there is no interference with the filters in the filter bar. Alternatively, the views might be made up of specific groupings or configurations, such as By X or By Y.

We strongly recommend that you use the segmented button and the select control as follows:

A limited set of views (2-3) can be represented by a segmented button (sap.m.SegmentedButton), which should collapse into a dropdown on a smartphone.
If the number of views can change or is larger than 3, they should be represented by a select (m.Select) control.

For more information about using multiple predefined views, see the list report floorplan (under Content Area: Multiple Views)

You can also include counters on your segmented buttons or your dropdown to indicate, for example, the number of products in each specific content view. For example, All Products (115), Hardware (60), Software (55).

Segmented button with a counter included

If you use a content switch, you no longer need a title. In very rare use cases, both a title and a content switch must be visible. In this case, the title and the content view are left-aligned.

Segmented text button to switch content

Select to switch content

You can also use the icon tab bar as a filter. At the front, there can be an All tab (optional) stating the overall number and type of items, such as 14 Products.

If you use the icon tab bar as a filter, we strongly recommend that you show a counter on every tab. If you need a counter, use the icon tab bar instead of the content switch inside the table. Also use the icon tab bar if you need different actions for your different table views. Use the content switch instead of tabs if there are multiple table variants.

Search (Generic)

If a dataset is too large for users to find items by scanning through them, we recommend that you offer a search functionality. Do not place a search function in the table toolbar if there is a filter bar above.

If you want to provide a search for your table, place it on the right side of the toolbar. Note that this control cannot be moved into the overflow menu. We therefore recommend that you define a minimum width.

For more information, see search.

Search in the table toolbar

Edit (Generic)

Sometimes the user will need to edit a table. In this case, you have two options: You must decide whether the user needs to edit more than one element, or whether the main use case is to edit only one element.

Option 1: Editing Line Items

To allow the user to edit a line item details page, set sap.m.ListType to “detail” in the corresponding item (sap.m.ColumnListItem/sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This creates an Edit button at the end of the line. The user can click or tap the button to trigger the edit event. Use this event to switch the corresponding line item to edit mode.

Edit is a list item type and therefore cannot be used together with navigation or with the use of click events on the whole item (active).

Option 1: Editing an individual line

Option 2: Editing the Whole Table

To edit a whole table, use the table toolbar. The edit function is a text button. Triggering this action results in the Edit button being replaced by Save and Cancel, and the user can then make any necessary changes in the table. All actions that control the UI of the table remain visible, and all other actions are hidden.

Table in view mode

Table in edit mode

View Switch (Generic)

View switches are right-aligned in the toolbar and allow the user to switch between different chart types or table layouts. You must provide the view switch if the chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the table view.

Switches are optional and do not have to be available if there is no need to switch between different charts or tables.

The number of chart types and switches must be used with caution. Each app team must decide what kinds of chart types make sense to visualize the respective data to assist the user in the best possible way.

We do not recommend using more than three types of visualization. The sequence of chart type switches is not fixed; however, you must sort them in terms of their importance and frequency of usage.

The chart type currently in use is highlighted. For this purpose, use a segmented control with icons. For more information about the icons and the chart types they represent, see chart toolbar.

Create / Add (Generic)

The Create or Add actions can be presented by a generic icon button or a text that describes the action in more detail. Place the action as close to the content as possible.

If the Create or Add action is a main function, the action should never be moved into the overflow.

If the app uses more than two Create or Add actions, or if the meaning of the icon is not entirely clear, use text buttons.

Add as icon button

Add as text button

Sort, Filter, and Group (Generic)

Sort, Filter, and Group can appear in any combination or as single actions. If you use more than one of these actions, we recommend keeping them in the following order: Sort, Filter, and Group.

When the user chooses one of these actions, the view settings dialog appears. This dialog can provide any combination of these three settings, including only one setting, such as Sort.

If sorting, filtering, and/or grouping is a common use case in your app, offer one, two, or all three of the corresponding features in one or more view settings dialogs. Do not provide these features if the table is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering in the view settings dialog; use the filter bar instead.

There are two ways to trigger the view settings dialog:

The user clicks or taps a button on the table toolbar. Offer all relevant functionality (Sort, Filter, and/or Group) in this dialog.
The user clicks or taps one of several buttons for each of these view settings. Each button opens a view settings dialog which contains only the corresponding page.

Use one of the two options listed above based on the following guidelines:

If sorting, filtering, and/or grouping are a secondary use case, use option 1.
If there are several additional actions and the table toolbar becomes overloaded with buttons, use option 1.
If sorting, filtering, and/or grouping are a primary use case, use option 2 to allow faster access to these settings.
If screen real estate is not an issue, use option 2.
If there is only one view setting (Sort, Filter, or Group), use option 2.

Always use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

Using the view settings dialog allows you to define several Sort, Filter, and/or Group settings per column. Thus, a column with several data points can be sorted, filtered, and/or grouped independently by each data point.

Ensure a consistent user experience. When a user reopens the app, show the table with the same view settings that were last defined by this user.

Option 1: One trigger for all view settings (sort, filter, and group)

Option 2: Multiple triggers for the different view settings (sort, filter, and group)

Personalization (Generic)

Use the table personalization dialog for adding, removing, and rearranging columns. The user triggers the dialog by clicking a button on the table toolbar.

Offer personalization if you need more columns than those that fit on a tablet screen (which is usually five) to fulfill 80% of your main use cases. Before you do this, try to reduce the number of columns, for example, by using several lines per column or by using the pop-in.

Ensure a consistent user experience. When a user reopens the app, show the table with the same settings that were last defined by this user.

Table toolbar with personalization icon

Export to Spreadsheet (Generic)

The Export to Spreadsheet action allows the user to export table rows and can be represented by a generic icon button. Place the action as close to the content as possible.

Example of a table toolbar with the 'Export to Spreadsheet' icon

Print (Generic)

The action for printing table items can be represented by a generic Print icon ().

Example of table toolbar with Print icon

Overflow (Generic)

Please see the section on overflow in the Behavior and Interaction section of the toolbar overview article.

Styles

The table toolbar is always transparent and and has transparent-style buttons. Do not use the accept, reject, or emphasized button styles; these are reserved for key actions in the footer toolbar. For more information, see button.

Guidelines

Please see the Guidelines section in the toolbar overview article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Action Sheet (guidelines)
Button (guidelines)

Implementation

Overflow Toolbar (SAPUI5 samples)
Action Sheet (SAPUI5 samples)
Personalization Dialog (SAPUI5 samples)
Toolbar (SAPUI5 samples)
Overflow Toolbar (SAPUI5 API reference)
Action Sheet (SAPUI5 API reference)
Footer Toolbar (SAPUI5 API reference)
Table Personalization Dialog (SAPUI5 API reference)
Toolbar Separator (SAPUI5 API reference)
Toolbar Spacer (SAPUI5 API reference)

Variant Management

Variants store view settings, such as filter settings or control parameters.

The filter settings consist of filter parameters, selection fields, and the layout of filters. They are set within the filter bar.

Control parameters are the sort order, filter and group settings, column visibility, and the layout of a table or chart. They are set within the toolbar of the control.

The variant management control enables the user to load, save, change, and maintain variants.

Information

Note on terminology:

On the user interface, we now call variants “views”, which is better understood by end users. To describe the SAPUI5 controls, however, we still speak of “variants” and “variant management”.

Usage

Use the variant management control if:

The user needs to save and load different filter settings to find the relevant data.
The user needs to save and load different layouts (for example, a table) to display data in different views.
The user needs to save the settings for the whole page, including the filter settings and table layout.

Responsiveness

Size S (Smartphone)

On phones, the My Views dialog for selecting variants, the Manage Views dialog, and the Save View dialog open in full screen mode.

My Views

Manage Views

Save View

Size M (Tablet)

My Views

Manage Views

Save View

Size L (Desktop)

My Views

Manage Views

Save View

Components

Variant management come with several components:

A clickable title with an icon
The My Views dialog for selecting variants
The Manage Views dialog for setting view parameters and deleting views
The Save View dialog for creating a new view

Name of View

The view name is the entry point for opening the My Views, Manage Views, and Save View dialogs.

If the user has made changes to the user interface that affect the saved view, the view is marked with an asterisk (*) to indicate the unsaved changes. This happens when the user deletes or adds a filter to the filter bar, for example.

Selecting a view

My Views Dialog

The My Views dialog contains all favorite views, including the default view, the pre-shipped standard views, and the views marked as favorites by the user. The default view and the pre-shipped standard views are marked as favorites automatically.

Default View

There can only be one default view, which the user can change in the Manage Views dialog. If the user sets a new default view, the last view remains as a favorite. The user can explicitly unfavorite the last view in the Manage Views dialog.

Pre-Shipped Standard Views

The standard view is the minimum set of filters delivered by SAP, and cannot be modified or deleted. It is flagged as a favorite and cannot be removed. There can be several pre-shipped standard views, depending on the use case.

Favorite Views

Users can mark views as favorites (or unfavorite them) in the Manage Views dialog. If more than 10 favorite views exist, a search option is displayed.

The views created by users themselves are favorited automatically, while views created by other users are unfavorited by default. This prevents the My Views popover from becoming overcrowded with public variants that are not relevant for the user.

The user can also mark public views as favourites.

Public Views

Public views are visible to all users who have access to the app. A view can be set to Public by individual users, key users, SAP (default delivery), or partners. All views that are set to Public are available within the Manage Views dialog.

A public view can be edited by the user who created it and by key users. All other users can only display the public view.

Actions in the My Views Dialog

Users can open the Manage Views dialog using the Manage button in the footer bar of the My Views dialog. From this dialog, users can Save changes to the current view, or choose Save As to create a new view, which opens the Save View dialog.

'My Views' dialog with a few views

'My Views' dialog with more than 10 views and a search option

Manage Views Dialog

In the Manage Views dialog, users can make the following changes:

Mark a view as a favorite
Change the name of a self-created view
Set a view as the default
Apply the view automatically
View the Sharing and Created By information of each view
Delete a self-created view

In addition to the personal views users create for themselves, they can also see the pre-shipped and public views. A user can only modify his or her own views, and not public, pre-shipped, or third-party views created by other users.
Exception: Key users can also change and delete views created by others.

'Manage Views' dialog

Save View Dialog

The Save View dialog is for creating a new view. For each view, you can make the following settings:

View: Name of the new view (required field)
Set as Default: If checked, the new view is the new default view.
Public: If checked, the new view is available to everyone who has access to the app.
Apply Automatically: If checked, the view is applied immediately whenever it is selected. The user does not need to click the Go button in the filter bar.
We do not recommend checking this option if the selection is likely to cause long loading times.

'Save View' dialog

Layout

The variant management control is merged with the page title (or next to or merged with title of the respective control, such as a table).

Filter Bar (Page Title)

The variant management control is merged with the page title within the page header container, and saves the stored filter settings or both the filter and control settings.

Variant management within the filter bar, merged with the page title

Table

The variant management control can also store control settings like layout, table column visibility, sorting, or grouping independently of the filter settings.

It is either merged with the control title or placed next to it.

If you place the title or variant management control inside a toolbar, apply the following styles:

Set the toolbar height to 3 rem.
Use a transparent toolbar.
Use the title class “sapMH4Fontsize”.

Variant management within the table toolbar

If the table has a separate title, place the title first.

Variant management with table title

Behavior and Interaction

This control allows the user to select, create, update, and delete variants for filter settings and control parameters such as layout, table column visibility, sorting and grouping.

My Views dialog: Selecting a View

The page title displays the active variant. Clicking the title dropdown opens a popover that displays all available variants. The currently active variant is highlighted. To load another variant, the user simply selects one from the list.

Save

Save can only be applied to variants that the user is allowed to save. Otherwise, this button is disabled. Save overwrites the active variant.

Save As

Save As enables the user to save the current filter settings as a new view. The Save As function can also be used to duplicate existing variants for later modification.

Manage

Manage opens the Manage Views dialog that allows the user to update, delete or favorite/unfavorite existing variants.

Selecting a view

Save View dialog

The Save View dialog is for creating new views. Providing a name for the new view is mandatory. Clicking or tapping OK saves the new view.

Save View

Manage Views dialog

In the Manage Views dialog, the user can rename, delete, and change properties of existing views.

Users can only modify or delete entries if they have the necessary permissions. By default, variants that a user has created can also be modified and deleted.

Manage Views

Save as Tile

The user can save the currently selected variant as a tile on the launchpad using the Save as Tile action in the Share menu.

In the Save as Tile dialog, the user can define the tile title and subtitle, a description, and the launchpad group in which the tile should appear.

Save as tile via 'Share' button

'Save as Tile' dialog

Guidelines

Save as Tile

Use the name of a variant as the title of the application tile. Map this as a preset title that cannot be edited by the user. In this case, whenever the variant is updated, the tile is updated accordingly.

Exception: If the variant cannot be referenced directly due to technical limitations, offer the standard tile creation option where filter parameters and settings are only saved within the URL.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Responsive Table (guidelines)
Table Toolbar (guidelines)
Filter Bar (guidelines)

Implementation

Variant Management (SAPUI5 samples)
Variant Management (SAPUI5 API reference)

View Settings Dialog

The view settings dialog helps the user to sort, filter, or group data within a (master) list or a table. The dialog is triggered by icon buttons in the table toolbar.

Usage

Use the view settings dialog if:

You need to allow the user to sort line items in a manageable list or table (up to about 20 columns).
You need to offer custom filter settings in a manageable list or table (up to about 20 columns).
You need to allow the user to group line items in a manageable list or table (up to about 20 columns).

Do not use the view settings dialog if:

You have complex tables (more than about 20 columns).
You need to rearrange columns within your table. Use the table personalization dialog instead.
You need very specific sort, filter, or column sorting options within complex tables. Use the P13n dialog instead.

Button Placement

For sorting, filtering, and grouping, place the corresponding icon button for each function directly in the toolbar.

Do not place sort, filter, or group buttons in the footer toolbar if they refer to a table.

For detailed information about where to place the sort, filter, and group buttons, see Sort, Filter, Group (Generic) in the table toolbar article.

Sort, Group, and Filter a List

You can also offer the view setting features for a list.

Responsiveness

The popover dialog appears as a modal window on desktop and tablet screen sizes, but full screen on smartphones.

The view settings dialog is a composite control that consists of a modal dialog with a maximum of three tabs with lists of attributes. Each helps the user to either sort, filter, or group a table or list. If the use case requires only a sort feature, for example, you can hide the filter and group tabs.

The dialog is triggered by the icon button in the table header

View settings dialog - Size S

View settings dialog - Size M

View settings dialog - Size L

Behavior and Interaction

The sort, filter, and group features can all be applied to a table simultaneously.

Sort

The first tab in the view settings dialog is the sort feature. The tab shows a standard sort icon with two arrows – one pointing up, and one pointing down (see image above).

The sort dialog shows two groups of sort settings. The first group offers general Ascending and Descending sort options. The second group offers attributes that fit the use case, such as Product, Supplier, Weight, or Price. The attributes can match the table columns, but because a table column can also contain several data points, such as “Name” and “Surname”, the attributes allow an attribute to be shown for each data point.

The user select attributes using the radio buttons. Clicking or tapping OK closes the dialog and shows the table items in the selected order.

Filter

The second tab in the View Settings dialog is the filter feature. The tab shows a filter, which is the standard filter icon. The filter tab can offer a single filter selection list, a multi-filter selection list, or a category list. The category list provides an overview, and allows the user to drill down to detailed filter selection lists.

The dialog for choosing a category from the filter tab drills down to the filter settings.

The dialog after choosing a general filter category (here: Weight). You can refine the filter further by selecting subcategories.

A table view filtered by 'Weight'. The info bar shows the filter setting.

Filter Selection List – Single Selection

The dialog offers one single-selection list with radio buttons to select a filter. This list is useful for offering a list of preconfigured filters for a specific use, such as “Products with numbers ‘starting between 100 and 200’ with status ‘in stock’ and color ‘green’”.

Filter Selection List – Multi-Selection

You can also offer a filter selection list as a multi-selection list. In this case, the user can choose, for example, all “green” and “red” products.

Selection of multiple filters

Category List

The filter dialog shows a single list of general filter categories depending on the use case, like Price or Height. The user chooses a category by clicking or tapping the list item, such as Price. As this is a simple drilldown, these categories do not offer radio buttons. The dialog shows a list of filter settings in the Price category. Optional filters here, such as Less than 100, depend on the use case. The user chooses a filter setting by selecting one of the radio buttons offered in this list. Clicking or tapping OK closes the dialog and shows the table items filtered by the selected attribute. The info bar shows which filter has been set.

Free-Form Apps

You can also customize your own filter UIs, for example, to support date picking.

Filter Values

Filters can correspond to single values as well as groups, such as “<100.00 EUR”.

Filter Reset

The refresh button on the filter tab resets all filter settings.

Removing Filters

Be sure to offer an entry such as None in a single-selection list. This enables users to remove a set filter.

Group

The third tab in the view settings dialog is the group feature. The tab shows an icon with lines in square brackets, which is the standard group icon.

The group dialog shows two groups of attributes. The first group offers a general Ascending or Descending order, which allows the user to select the order in which the defined groups appear. The second group offers attributes that fit the use case, such as Type or Supplier.

You can also offer an attribute like Price to group data in a table.

The user uses the radio buttons or selects checkboxes to choose attributes. Clicking or tapping OK closes the dialog and shows the table with items grouped below headers.

Dialog for choosing an attribute from the group tab

A table view grouped by supplier – Group headers divide the list

Naming Group Headers

Be sure to name the group headers as follows: Category Name: Value/Range. For example, Category: Accessories, or Supplier: Red Point Stores.

Guidelines

For opening the dialog from a table toolbar, use different buttons for each function (sort, filter, group). With each button, open the View Settings dialog with just the corresponding tab.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Table Overview (guidelines)
Table Toolbar (guidelines)
Table Personalization (guidelines)
P13n Dialog (guidelines)

Implementation

Table View Settings (SAPUI5 samples)
Table View Settings (SAPUI5 API reference)

Step Input

The step input control allows the user to change the input values in predefined increments (steps).

Usage

Use the step input if:

The user needs to adjust amounts, quantities, or other values quickly.
The user needs to adjust values for a specific step (for example, in a shopping cart).

Do not use the step input if:

The user needs to enter a static number (for example, postal code, phone number, or ID). In this case, use the regular input field control instead.
You want to display a value that rarely needs to be adjusted and does not pertain to a particular step. In this case, use the regular input field control instead.
You want the user to enter dates and times. In this case, use the date picker, date range selection, time picker, or date/time picker instead.

Responsiveness

Size S and M (Smartphone and Tablet)

On smartphones and tablets, the step input is shown in cozy mode. When the focus is in the input field, the keyboard layout for numeric input is displayed.

Size L (Desktop)

On desktop devices, the step input is shown in compact mode.

For more information on the cozy and compact modes, see content density.

Step input - size S/M

Step input - size L

Components

The step input consists of an input field and buttons with icons to decrease or increase the value.

Step input areas

You can show a descriptive reference or unit of measurement after the field (property: description). Depending on your use case, you may need to adjust how the space is distributed between the input field and the descriptive text (property: fieldWidth).

Step input with description

Behavior and Interaction

Default Value

The step input always contains a value. When no value is set, the default value is generally 0. However, app developers can set a different default value (property: value).

If the minimum value is larger than 0, the generic value is the minimum value set by the app team.

Changing the Value

The user changes the value:

By pressing the increase/decrease buttons
By typing a number
With keyboard shortcuts (up/down, page up/down)
With the mouse scroll wheel

On desktop devices, clicking the input field places the cursor in the input field. On mobile devices, tapping the input field displays the numeric keyboard.

Clicking the buttons changes the value by a step and does not place the caret in the input field.

When the user clears the value and leaves the input field, the value in the field becomes 0 or the minimum if the minimum is larger than 0.

If the user enters an invalid value, the invalid value remains in the input field. An error state is displayed.

Increasing the Step

To allow the user to change values by a larger step with keyboard shortcuts, app developers can set a multiple of the step (property: largerStep). The default value is two times the set step.

If your use case requires more complex step increments (for example, if you want the step increment to be the closest number that is divisible by the defined step) you can use the stepMode property. For details, please refer to the API reference.

Maximum and Minimum Values

App developers can set a maximum and minimum value for the step input.

When the maximum/minimum values are reached, the Increase/Decrease button and up/down keyboard navigation are disabled.

Display Value

The step input control allows decimal values and can control the number of digits shown after the decimal point (property: displayValuePrecision). When the property is set to a specific value – from 0 (default) to 20 – the control restricts users accordingly as they type or paste a value. Trying to type more digits triggers an error state.

Step input at maximum value (max = 100)

Step input at minimum value (min = -100)

Styles

The step input has different styles for its four states: default, warning, error, and success.

Default state

Warning state with value state text

Error state with value state text

Guidelines

Always provide a meaningful label for the step input.

Width

By default the width of the step input is set to 100% of the container. Avoid setting a fixed width, but rather embed the control in a proper layout such as a form, simple form, or grid layout, and use the layout data property where the width is defined by the 12-column approach to define the responsive behavior for sizes S, M, and L.

When used in forms, the width of the step input control comes from the label:field ratio of the form. The app development team should be able to restrict the width to a proper number of columns (12-grid responsive layout) so that the step input is not too wide.

Ensure an appropriate width for the range of values to be entered for all the sizes S, M, and L. Avoid a larger width than necessary.

Keep in mind the varying lengths of decimals. Limit the number of digits after the floating point if possible in your use case. For more information, have a look at the article on formatting numbers.

Properties

Value States

The step input control offers the four value states listed below. For the error and warning states, you can show an additional value state text when the focus is on the input field.

None (default): No value state message is shown
Warning
Error
Success: No value state message is shown

For more guidance on when to use which state, see message handling. For more information on showing value states in a form, see form field validation.

Default state

Warning state

Error state

Editable and Enabled States

Editable

Property settings: editable = true, enabled = true

The step input control is enabled and editable by default. Set the control to editable to allow the user to enter a value.

Not Editable

Property settings: editable = false, enabled = true

Use this state, for example, to display data only.

Disabled

Property settings: editable = not relevant, enabled = false

Set the control to disabled in an edit scenario to indicate that the user cannot change the control, for example, due to missing access rights or previous conditions not having been fulfilled or selected.

Read-only state

Disabled state

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Input Field (guidelines)
Button (guidelines)

Implementation

Step Input (SAPUI5 samples)
Step Input (SAPUI5 API reference)

Token

Tokens are small items of information (similar to tags) that mainly serve to visualize previously selected items. The tokenizer is the container that handles the tokens. Tokens can be added, removed, selected, or deselected.

Token

Usage

Use tokens only in the multi-combo box, multi-input control, or value help dialog.

Components

The tokenizer is an invisible container that can display multiple tokens.

Tokens have the following properties:

They usually contain single text items.
They may also contain key-value pairs, such as John Miller (ID1234567).
They contain a Remove icon , which is invisible if the token is in edit mode.

Tokens with a surrounding tokenizer

Behavior and Interaction

Interacting

Users can interact with tokens using a mouse, keyboard, and/or touch input. In size L (desktop) only, hovering with the mouse over the token produces a tooltip with the entire content of the token (on a maximum of two lines).

Selecting and Deselecting Tokens

Users can select tokens by clicking them, or by using the keyboard. The selected tokens are then indicated. Users can select multiple tokens separately by holding down the CTRL key and selecting the relevant tokens, for example, by clicking them.

The user can select a series of tokens by placing the cursor in an initial position (which can also be a token), holding down the SHIFT key, and clicking a new position. The tokens between these two cursor positions are then selected.

Adding Tokens

The user can add tokens to the multi-combo box and multi-input control. New tokens are added in the order in which they are entered.

Information

For information on how to manage leading and treading whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Removing Tokens

The user can instantly remove tokens via the keyboard, or by clicking the Remove icon .

Styles

There are five different styles of tokens: regular, on hover, selected, selected on hover and read-only. These styles correspond to the type of interaction being used.

Regular

On hover

Selected

Read only

Hover selected

Guidelines

The tokenizer can also be used as a tag container.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Multi-Combo Box (guidelines)
Multi-Input Field (guidelines)
Value Help Dialog (guidelines)
Combo Box (guidelines)

Implementation

Tokens (SAPUI5 samples)
Tokenizer (SAPUI5 samples)
Tokens (SAPUI5 API reference)
Tokenizer (SAPUI5 API reference)

Calculation Builder

Message Strip

The message strip is a control that is used as an information bar. It contains information about an object or a status and can be embedded within the detail area of an object or page.

Usage

Use the message strip if:

You want to provide information within the detail area of an object.
You want to inform your user about a status of an object.
You want to warn your user about an issue.

Do not use the message strip if:

You want to display information within the object page header, within a control, in the master list, or above the page header.

Responsiveness

The message strip is fully responsive. Icons within the message strip are displayed to the left (custom icons) or right (Close action) of the message. Text and links behave differently and wrap.

If you place the control within the detail area, it will always use 100% of the width and react to the responsiveness of the container.

Message strip on a smartphone (size S)

Message strip on a desktop (size L)

Types

The following semantic types are available.

Information
Warning
Error
Success

Different semantic types and colors

Behavior and Interaction

Static behavior

The message strip acts as an information bar. If you want to display a status related to an object, keep the interaction static and do not show the Close button.

Static behavior used to display a status

Interactive behavior

Clicking the Close button on the right side hides the message strip.

Interactive behavior with close function

Properties

sap.m.MessageStrip is limited to the following properties:

Property:showIcon – Allows you to display an icon before the text
Property:customIcon – Allows you to display an icon from the icon library
Property:type – Changes the semantic color and the icon in front of the message strip
Property:text – Adds text to the control
Property:link – Adds a link
Property:showCloseButton – Adds a Close button

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Message Handling (guidelines)

Implementation

Message Strip (SAPUI5 samples)
Message Strip (SAPUI5 API reference)

Date/Time Picker

The date/time picker allows users to select date and time values in a combined input.

Usage

Use the date/time picker if:

You need a combined date and time input control.

Do not use the date time picker if:

You want to use either a date or a time value. In this case, use the date picker or the time picker instead.

Responsiveness

The date/time picker runs on all form factors and fully adapts to all devices.

The date/time picker opens in a popover for sizes M and L (tablet or desktop device)

The date/time picker opens in a dialog for size S (smartphone)

Behavior and Interaction

Selecting Date and Time Values

Sizes M and L/XL

The date/time picker appears as a popover when the user clicks or taps a date (input field) on the calendar. The user can then select the desired date from the calendar, and the time from the rotating wheel. For the time, it’s possible to select hours, minutes, and even seconds.

When the user clicks or taps the OK button, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Date/time picker – Open

Date/time picker – Closed

Size S and Mobile Size

On smaller devices, the user can choose the date and time value in arbitrary order by tapping the segmented button on top of the screen. Be aware that the popover is superimposed on the input field during the selection process for mobile/S sizes.

The user can select the desired date from the calendar, and the time from the rotating time wheel. For the time, it’s possible to select hours, minutes, and even seconds. Clicking a date in the calendar automatically takes the user to the time selection screen.

When the user selects OK, the popover closes and the selected date and time appear in the input field. When the user selects Cancel, the action is aborted and the input field remains unchanged.

Size S - Date/time picker opens with the 'Date' view

Size S - Selecting a date opens the 'Time' view

Scrolling

Within the date/time input popover, each area can be scrolled individually by dragging and dropping the areas.
On large devices, the user can also use the standard scrolling mechanism.

Date/time input – Scrolling by swiping

Guidelines

Date Picker and Time Picker

In general, we recommend separating the date/time picker controls as the time picker supports the mask input function and the date picker allows the user to enter date in different formats. This makes it easier and more convenient for the user to enter the desired values. For additional guidelines and information on the individual controls, see the resources section below.

Default Values

Independently of the chosen control, set the default values of the date/time picker carefully to avoid unnecessary scrolling. It often makes sense to set the default for the time to the full or half hour, setting the minutes to 00 or 30. Sometimes, it may also make sense to use the current time and date.

Formatting Dates and Times

For guidelines and information on the SAPUI5 date formatters, see formatting dates.

For guidelines and information on the SAPUI5 time formatters, see formatting times.

Setting Steps

You can set intervals for the minutes and seconds on the slider (properties: minutesStep and/or secondsStep). For example, if you set the seconds step to “5”, the slider offers “00”, “05”, “10”, “15”, and so on.

Properties

AM and PM are locale-dependent. The locale can be set using the property localeId.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Time Picker (guidelines)
Date Picker (guidelines)
Formatting Time (guidelines)
Formatting Dates (guidelines)

Implementation

Date Time Picker (SAPUI5 samples)
Date Time Picker (SAPUI5 API reference)

Time Picker

The time picker allows the user to select a localized time. It can be used with touch, mouse, or keyboard input.

Usage

Use the time picker if:

You want the user to select a time.
You want the user to select a time range. In this case, one time picker can be used to set the starting time and a second one to set the end time.
You want the user to select a detailed duration, such as 1 minute and 30 seconds.

Do not use the time picker if:

You want the user to select a duration such as 15 minutes, 30 minutes, 1 hour, or 2 hours. In this case, use the select control instead.

Responsiveness

The time picker comes with a cozy mode and a compact mode. In the compact mode, the time input field and the button are smaller than in the cozy mode. In the compact mode, there are also arrows that the user can click or tap to set hours, minutes, and so on. For more information, see the article on content density.

On desktop (size L/XL) and tablet (size M) devices, the user can enter a time in the input field of the time picker, or set a time via the time picker dropdown which opens when the user clicks the time picker button.

For mobile (size S) devices, the tap area is the same as for a tablet, and the user can type a time in the time input field. Unlike on a tablet or desktop, the time picker dropdown does not open below the time input field, but rather in a subview.

Comparison of cozy mode (left) and compact mode (right)

Components

The time picker consists of a time input field and a time picker button. On desktop, tablet, and mobile devices, both elements have their own click area. Clicking the time picker button opens the time picker dropdown.

You can set a predefined time, which shows as the initial value in the time input field and the time picker dropdown. Users can overwrite the initial value manually at any time.

Time picker input

Time Input Field

The time input field allows the user to enter a time directly in the field, or select it using the time picker dropdown. The input is validated and feedback is given to the user.

The time input field can also contain a placeholder (input prompt).

Time Picker Button

When the user clicks or taps the time picker button, the time picker dropdown opens to allow the user to choose a time.

Time Picker Dropdown

In the time picker dropdown, the user can select a time by setting hours, minutes, seconds and AM/PM or a subset of these (with hours and minutes only).

Dropdown with hours and minutes

Dropdown with hours, minutes, seconds, and AM/PM

Behaviour and Interaction

Selecting a Time (Desktop Device)

The user clicks the time picker button, which opens the time picker dropdown. In the time picker dropdown, the user can set the time either with the mouse or by using the keyboard arrows. The Page Up and Page Down keys can also be used to set the current selection to the lowest or highest value, and the Home and End keys can be used to go to the first or last element of the picker.

When the desired time has been selected, the user can confirm this selection by clicking the OK button. If the user wants to close the dropdown without changing the time to the selected time, this can be done by clicking the Cancel button or by clicking outside the dropdown.

Preventing Errors

The user can also select a time by clicking the time picker input field and typing the desired time in the field. You can prevent users from making incorrect entries by not allowing them to type in certain characters (see mask input). If the user enters a time that has the correct format but is invalid (such as 12:60:85), the time picker displays a validation error.

You can switch off the integrated mask input feature, but we strongly advice against doing so. Only deactivate the mask input if you need to make an exception for your use case (for example, if a variable length is required for a specific locale).

Time picker dropdown and input field

Selecting a Time (Tablet or Mobile Device)

On tablets and mobile devices, users can select the time by tapping the time picker button. The timer picker dropdown opens beneath the input field (a subview is opened on mobile devices). The user sets the hour by touching the hour element and then swiping up or down. To set the minutes, seconds, and AM/PM, the user also touches the corresponding element and swipes up or down to set the right value.

To confirm the selected time, the user taps the OK button. Taping the Cancel button cancels the selection. On tablets, the selection can also be cancelled by tapping outside the time picker dropdown.

Set the time by swiping up and down (tablet)

Style

Disabled Time Picker

In the disabled state, the time picker input is grayed out and the button becomes invisible.

Validation Error

When an invalid time is typed in, the time picker's border turns red and an error message appears.

Guidelines

Time Formats

Only let the user select time in seconds if this information is really necessary.

If the user has to set a time that is timezone sensitive, always provide information about the timezone. For example, if you want the user to choose a time on a calendar for a meeting that might also involve people from other timezones, provide information about those timezones. Ideally, you should also display the local time in the other attendees’ timezones so that the user can choose a time that is convenient for everyone.

12-Hour System

In the 12-hour system, the date picker can contain selections for hours, minutes, seconds, and AM/PM.

24-Hour System

In the 24-hour system, the date picker can contain selections for hours, minutes, and seconds. AM/PM is not available in this mode.

For more information, see formatting time.

Properties

AM and PM are locale-dependent. Therefore, the locale can be set using the property “localeId”.

You can set the display format (property: displayFormat) to define the format in which the time input field and the time picker dropdown display the time. For more information about time formats, see the article on formatting dates.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Date Picker (guidelines)
Date/Time Picker (guidelines)
Input Field (guidelines)
Select (guidelines)
Formatting Time (guidelines)
Formatting Dates (guidelines)

Implementation

Time Picker (SAPUI5 samples)
Time Picker (SAPUI5 API reference)

Table Toolbar

The table toolbar always appears above the table and has a transparent background. The control is used for key actions that impact the entire table.

Usage

Use the table toolbar if:

There are multiple objects on your page and you need to edit only the table.
You want to show actions as close to their corresponding controls as possible.
You need a title for your table.

Do not use the table toolbar if:

You are using single selection and only one or two actions. In this case, place the actions on each line.

Responsiveness

To enable responsiveness, use the OverflowToolbar control. For more information, please refer to the corresponding section in the toolbar overview article.

Components

All of the components are optional. The table toolbar can contain the following actions:

App-specific actions
Generic actions

The following actions count as generic:

Title
Variant management
Switch
Search
Edit
Create (for new items)
View switch
Add (for exsiting items)
Sort, Filter, and Group (view settings)
Personalize
Export to Spreadsheet
Print
Overflow

Example of possible components

Behavior and Interaction

App-Specific Actions

If needed, the app team can define their own actions for the app. In this case, the text buttons should contain a short, unambiguous text that explains what action the button performs. A button text is usually a single-word verb (for example, Share). Note that translated UIs may increase the length of the text string.

Only use icon buttons if you are sure that the user will be able to interpret the meaning of the icon easily and without the aid of a tooltip. Use standard and easily recognizable icons, such as a paper clip for an attachment.

Table toolbar with app-specific icon buttons

Title (Generic)

A title provides a short, meaningful summary of the content, mostly by using a single word. The title bar is a toolbar property that supports consistently-sized text and titles with the same height in cozy and compact form factors.

Consider the following when using a title:

Use the sap.m.Title control.
The toolbar height must be set to 3 rem.
The title must have the label class sapMH4Fontsize.

Use a table title if you need the table toolbar, and if the title of the table is not indicated in the surrounding area. To avoid repeating text, feel free to use generic text as a table title, such as Items. Note that the title becomes truncated if there is not enough space.

Title in the table toolbar

Variant Management (Generic)

Variants store settings that have been defined, for example, for layout, column visibility, sorting, and grouping. The variant management control enables the user to load, save, and change variants.

In the context of tables, the variant management control is used to save, manage, and load table settings which include layout, column visibility, sorting, and grouping.

For this, the variant management control can be used independently of the filter settings.

Always place this control in the table toolbar next to the title.

If you place the variant management control inside a toolbar, you need to apply the following styles:

The toolbar height must be set to 3 rem.
The title must have the class sapMH4Fontsize.

The examples below show where to place this control:

Variant in the table toolbar

Title and Variant Management (Generic)

In exceptional cases, both the title and variant management have to be used. However, we do not recommend this because it results in a crowded toolbar and problems with responsiveness may occur. Variant management alone is generally sufficient.

The title and variant management are both left-aligned. The title is placed first, followed by a separator and the variant management.

Title with variant management

Content Switch (Generic)

When apps need to switch between different content in a table, use a select control (also known as a dropdown) or a segmented button. The select control and the segmented button are displayed left-aligned in the table toolbar and allow the user to show different views.

These views could be very specific. For example, All, Mine, and Others. However, you should ensure that there is no interference with the filters in the filter bar. Alternatively, the views might be made up of specific groupings or configurations, such as By X or By Y.

We strongly recommend that you use the segmented button and the select control as follows:

A limited set of views (2-3) can be represented by a segmented button (sap.m.SegmentedButton), which should collapse into a dropdown on a smartphone.
If the number of views can change or is larger than 3, they should be represented by a select (m.Select) control.

For more information about using multiple predefined views, see the list report floorplan (under Content Area: Multiple Views)

You can also include counters on your segmented buttons or your dropdown to indicate, for example, the number of products in each specific content view. For example, All Products (115), Hardware (60), Software (55).

Segmented button with a counter included

If you use a content switch, you no longer need a title. In very rare use cases, both a title and a content switch must be visible. In this case, the title and the content view are left-aligned.

Segmented text button to switch content

Select to switch content

You can also use the icon tab bar as a filter. At the front, there can be an All tab (optional) stating the overall number and type of items, such as 14 Products.

If you use the icon tab bar as a filter, we strongly recommend that you show a counter on every tab. If you need a counter, use the icon tab bar instead of the content switch inside the table. Also use the icon tab bar if you need different actions for your different table views. Use the content switch instead of tabs if there are multiple table variants.

Search (Generic)

If a dataset is too large for users to find items by scanning through them, we recommend that you offer a search functionality. Do not place a search function in the table toolbar if there is a filter bar above.

If you want to provide a search for your table, place it on the right side of the toolbar. Note that this control cannot be moved into the overflow menu. We therefore recommend that you define a minimum width.

For more information, see search.

Search in the table toolbar

Edit (Generic)

Sometimes the user will need to edit a table. In this case, you have two options: You must decide whether the user needs to edit more than one element, or whether the main use case is to edit only one element.

Option 1: Editing Line Items

To allow the user to edit a line item details page, set sap.m.ListType to “detail” in the corresponding item (sap.m.ColumnListItem/sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This creates an Edit button at the end of the line. The user can click or tap the button to trigger the edit event. Use this event to switch the corresponding line item to edit mode.

Edit is a list item type and therefore cannot be used together with navigation or with the use of click events on the whole item (active).

Option 1: Editing an individual line

Option 2: Editing the Whole Table

To edit a whole table, use the table toolbar. The edit function is a text button. Triggering this action results in the Edit button being replaced by Save and Cancel, and the user can then make any necessary changes in the table. All actions that control the UI of the table remain visible, and all other actions are hidden.

Table in view mode

Table in edit mode

View Switch (Generic)

View switches are right-aligned in the toolbar and allow the user to switch between different chart types or table layouts. You must provide the view switch if the chart relies on subtle color differences or gradients of color. In these cases, users with visual impairments can switch to the table view.

Switches are optional and do not have to be available if there is no need to switch between different charts or tables.

The number of chart types and switches must be used with caution. Each app team must decide what kinds of chart types make sense to visualize the respective data to assist the user in the best possible way.

We do not recommend using more than three types of visualization. The sequence of chart type switches is not fixed; however, you must sort them in terms of their importance and frequency of usage.

The chart type currently in use is highlighted. For this purpose, use a segmented control with icons. For more information about the icons and the chart types they represent, see chart toolbar.

Create / Add (Generic)

The Create or Add actions can be presented by a generic icon button or a text that describes the action in more detail. Place the action as close to the content as possible.

If the Create or Add action is a main function, the action should never be moved into the overflow.

If the app uses more than two Create or Add actions, or if the meaning of the icon is not entirely clear, use text buttons.

Add as icon button

'Create' as a text button

Sort, Filter, and Group (Generic)

Sort, Filter, and Group can appear in any combination or as single actions. If you use more than one of these actions, we recommend keeping them in the following order: Sort, Filter, and Group.

When the user chooses one of these actions, the view settings dialog appears. This dialog can provide any combination of these three settings, including only one setting, such as Sort.

If sorting, filtering, and/or grouping is a common use case in your app, offer one, two, or all three of the corresponding features in one or more view settings dialogs. Do not provide these features if the table is expected to have only a small number of entries (up to 20 in most cases).
If filtering is a main use case, do not offer filtering in the view settings dialog; use the filter bar instead.

There are two ways to trigger the view settings dialog:

The user clicks or taps a button on the table toolbar. Offer all relevant functionality (Sort, Filter, and/or Group) in this dialog.
The user clicks or taps one of several buttons for each of these view settings. Each button opens a view settings dialog which contains only the corresponding page.

Use one of the two options listed above based on the following guidelines:

If sorting, filtering, and/or grouping are a secondary use case, use option 1.
If there are several additional actions and the table toolbar becomes overloaded with buttons, use option 1.
If sorting, filtering, and/or grouping are a primary use case, use option 2 to allow faster access to these settings.
If screen real estate is not an issue, use option 2.
If there is only one view setting (Sort, Filter, or Group), use option 2.

Always use only the view settings you really need. For example, do not offer grouping if it does not support your use case.

Using the view settings dialog allows you to define several Sort, Filter, and/or Group settings per column. Thus, a column with several data points can be sorted, filtered, and/or grouped independently by each data point.

Ensure a consistent user experience. When a user reopens the app, show the analytical table with the same view settings that were last defined by this user.

Option 1: One trigger for all view settings (sort, filter, and group)

Option 2: Multiple triggers for the different view settings (sort, filter, and group)

Personalization (Generic)

Use the table personalization dialog for adding, removing, and rearranging columns. The user triggers the dialog by clicking a button on the table toolbar.

Offer personalization if you need more columns than those that fit on a tablet screen (which is usually five) to fulfill 80% of your main use cases. Before you do this, try to reduce the number of columns, for example, by using several lines per column or by using the pop-in.

Ensure a consistent user experience. When a user reopens the app, show the analytical table with the same view settings (Sort, Filter, and Group settings) that were last defined by this user.

Table toolbar with personalization icon

Export to Spreadsheet (Generic)

The Export to Spreadsheet action allows the user to export table rows and can be represented by a generic icon button. Place the action as close to the content as possible.

Example of a table toolbar with the 'Export to Spreadsheet' icon

Print (Generic)

The action for printing table items can be represented by a generic Print icon ().

Example of table toolbar with Print icon

Overflow (Generic)

Please see the section on overflow in the Behavior and Interaction section of the toolbar overview article.

Styles

The table toolbar is always transparent and and has transparent-style buttons. Do not use the accept, reject, or emphasized button styles; these are reserved for key actions in the footer toolbar. For more information, see button.

Guidelines

Please see the Guidelines section in the toolbar overview article.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Action Sheet (guidelines)
Button (guidelines)

Implementation

Overflow Toolbar (SAPUI5 samples)
Action Sheet (SAPUI5 samples)
Personalization Dialog (SAPUI5 samples)
Toolbar (SAPUI5 samples)
Overflow Toolbar (SAPUI5 API reference)
Action Sheet (SAPUI5 API reference)
Footer Toolbar (SAPUI5 API reference)
Table Personalization Dialog (SAPUI5 API reference)
Toolbar Separator (SAPUI5 API reference)
Toolbar Spacer (SAPUI5 API reference)

Filter Bar

The filter bar filters item lists and tables according to various filter criteria. You can use it for both simple and complex lists, regardless of their size. To handle complex lists with multiple filters, the filter bar provides predefined, customizable filter sets (variants).

Filter bar within the dynamic page

Information

The filter bar now supports the dynamic page. Do not use the filter bar in the sap.m.Page for new SAP Fiori apps. For more information on the differences, see the filter bar guideline for version 1.52.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to run on all form factors. While the main concept of the filter bar remains stable across the devices, its responsive design adapts the control’s behavior to match the ability of each device.

Size S (Smartphones)

Expanded filter bar (size S)

Collapsed filter bar (size S)

Filter dialog (size S)

Size M (Tablet)

Expanded filter bar (size M)

Collapsed filter bar (size M)

Filter dialog (size M)

Size L/XL (Desktops)

Expanded filter bar (size L/XL)

Collapsed filter bar (size L/XL)

Filter dialog (size L/XL)

Layout

Filter Dialog

The filters inside the filter dialog are arranged in a vertical linear layout. If filter groups are maintained, the filters are visually grouped in sections, with the filter group name at the top. A link at the end of each group allows the user to add or remove filters from that group. The link text is Change Filters if at least one filter is activated, indicating that filters can be added or removed. If no filters have been set for the group, the link text is More Filters, indicating that more filters can be added.

The first group is called “Basic” and contains the preset filters that come with the app. A checkbox next to each filter enables the user to show the corresponding filter on the expanded filter bar. If the checkbox is selected, the filter is shown on the expanded filter bar. If the checkbox is not selected, the filter is only visible within the filter dialog. In both cases, the filter is active if a value is entered.

The vertical layout of the filter dialog remains stable across all devices. To ensure a clean grid layout appearance, the size of the widest input field is inherited by all other filters.

Filter dialog (size L)

Filter dialog (size S)

Expanded Filter Bar

The expanded filter bar arranges the input fields in a simple horizontal linear layout. If the browser’s window size is reduced or the filters exceed the first line, a simple mechanism opens a new line of filters. The height of the expanded filter bar is not limited and adjusts to accommodate the filters that need to be shown. The label is always above the input field. As in the filter dialog, the size of the widest input field is inherited by all other filters. This avoids having unstable and busy-looking grid layouts.

Filter bar (size L) with one row of filters

Filter Bar (Size L) with more than one row of filters

Filter bar (size S) with vertical filters

Components

Collapsed Filter Bar

The collapsed filter bar takes up very little space, leaving the bulk of the screen to display the actual results. However, the variant selector in the upper left corner is still available for switching between variants. The user can expand or collapse the filter bar by clicking on the header. If required by the use case, the filter bar can be expanded by default.

On desktop and tablet devices, the collapsed filter bar shows a summary of the filters currently applied. It shows Filtered By (x):, where “x” stands for the number of applied filters. This is followed by a comma-separated list of the filters currently applied. Up to 5 filters are listed. If more filters have been applied, an ellipsis (…) shows at the end of the string. If no filters have been applied, the summary text is Filtered By: None.

Collapsed filter bar

Expanded Filter Bar

Developer Hint

Smart filter bar: See the parameters for configuring the expanded filter bar.

In addition to the collapsed filter bar, the expanded filter bar shows a user-defined filter subset of the currently selected variant.

The Adapt Filters (x) link opens the filter dialog, and allows the user to add filters or hide them. The Go button triggers the filter. The Go button is only shown in manual mode.

Expanded filter bar

Filter Dialog

Developer Hint

Smart filter bar: See the parameters for configuring the filter dialog.

The filter dialog is the central component that shows all filters of the selected variant, allowing the user to add filters to the variant or remove them. Filters are arranged into their respective filter groups. The user can search for a specific filter by name in the search bar at the top.

The footer toolbar at the bottom of the dialog provides the following functions:

Save: Saves your modified variant filter set (Save and Save As can be provided)
Cancel: Closes the dialog and undoes all changes
Restore: Restores the initial variant values (you can hide this button if it does not fit the app’s use case)
Go: Executes the selected filter set
Clear (optional): Clears all input fields/filters (this button should only be used if it fits the app’s use case)

The user can choose to hide filters on the expanded filter bar by deselecting the relevant checkbox next to the filter in the filter dialog (for example, if a filter is rarely edited, or unimportant).

Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.

Variant selector

Filter/Input Controls

Developer Hint

For development information, see data types for the smart filter bar.

Filter/input controls

Which filter control is used in the filter dialog or the expanded filter bar depends on the use case. Use the value help control if you want to offer an advanced function for selecting single or multiple items either inline (by entering text) or by means of a dialog. If there is a predefined list for single or multiple selection, use the combo box control. For temporal information you can use the date picker or date range selector.

When designing the filter bar, pick the simplest input control that works for your use case. Using more complex controls (like value help) when you don’t actually need them just increases the complexity of the filter bar.

Additionally recommended input fields:

Behavior and Interaction

The filter bar contains the following actions:

Selecting a Variant

The main use case for the filter bar is to select and execute variants that influence the list of items. In this example, the variant applies its filter set automatically. The item list is filtered without the user needing to click Go.

Selecting a Variant

Adding Filters to a Variant

In the filter dialog the user can access more filters for every filter group. Filters can then be added or removed in a separate dialog. Once a filter has been added or removed, it appears or disappears from the filter dialog. If the user selects the checkbox next to the filter, the filter is displayed on the extended filter bar.

Adding Filters to a Variant

Personalizing the Expanded Filter Bar

Users can hide a filter on the expanded filter bar by deselecting the checkbox next to the relevant filter in the filter dialog. This allows the user to hide filters that are rarely changed from the extended filter bar, giving complex filters a more lightweight appearance.

Personalizing the Expanded Filter Bar

Guidelines

Default Variant Filters

For all filter bars, provide a set of predefined default filters that come with the app (“Basic” group in the filter dialog). Include filters that are:

Mandatory / crucial to the use case
Frequently used
Vital for reducing the number of items in the list

Users can hide filters in the “Basic” group, but cannot remove them from the filter dialog.

Default variant "Basic"

Default Values

Provide a meaningful default value for as many filters as possible. Meaningful default values depend on your use case.

A default value for date ranges, for example, should reflect the time frame the user would normally apply. App designers need to decide which time frame is appropriate.

Appropriate default values are particularly crucial for filter sets and list reports that operate on large datasets. In this case, consider making certain default filters mandatory to help the user avoid loading very large datasets unnecessarily.

Filter without default value

Filter with available values

Filter with a default value

Table Filtering and Table Searching

Provide the user with a central location filtering and searching. If you use a filter bar, do not provide filter options or search options for the control below (for example, a table, chart, or list.). Avoiding multiple filter locations also helps to prevent confusing or contradictory entries (for example between the filter bar and a table filter).

Do

Table without filtering option

Don't

Table with filtering option

Initial State

The filter bar can initially be collapsed or expanded, depending on the use case:

Initial State Collapsed

If the app has a default variant that is executed on loading, the table is prefilled, and the user seldom changes the filters, the app can start with a collapsed filter bar.

Initial State Expanded

If the app does not use a default variant and the user has to set a filter to obtain a first result set for the table, start with an expanded filter bar. Also, if a vast number of items are expected, include some mandatory filters. Since the user first has to enter values for these filters, start with an expanded filter bar. If you are in any doubt, start the app with an expanded filter bar.

Note: At least one filter must be defined to begin with. This filter is set within the basic group by app designers. If the use case allows, and depending on the size of the result set, provide a table that is initially filled.

Initial state collapsed

Initial state expanded

Basic Search Field

The basic search field allows the user to filter the results by a given keyword. In contrast to the other input fields, the basic search field has a placeholder text instead of a label.

Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.

Filter bar with basic search field

Manual Update / Live Update

The filter bar is available in two separate modes: manual update mode and live update mode.

Manual Update

With manual update, the filter results are only updated when the user clicks or taps Go. A Go button is therefore mandatory in manual update mode. Pressing enter on the keyboard also triggers the filter.

Live Update

With live update mode, the filter bar reacts instantly to every input change. The result table is updated every time the user changes a filter field or the search field. Therefore, a Go button is not necessary and is not shown if live update mode is used.

Additionally, the search is triggered with every letter that is entered. Starting with the first letter typed in, the table is updated with the results that match all set filters that include the search term.

Which One to Use

Use live update mode by default as it is more convenient for the user. If the user has to configure multiple filters to obtain a useful result set, or if the resulting traffic is expected to be excessively high, consider using manual update mode instead.

Filter bar in manual update mode

Filter bar in live update mode

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Variant Management (guidelines)
Smart Filter Bar Annotations (guidelines)

Implementation

Filter Bar (SAPUI5 samples)
Smart Filter Bar (SAPUI5 samples)
Filter Bar (SAPUI5 API reference)
Smart Filter Bar (SAPUI5 API reference)
Variant Management Example (SAPUI5 samples)
Variant Management Example (SAPUI5 API reference)
Filter Item (SAPUI5 API reference)
Filter Group Item (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multiselection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of an entry closes the option list and creates a token of the selected option. Every entry is accompanied by a checkbox (4) to allow multiselection. Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click or tap the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks or taps the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4), while the typed text remains in the input field. Selected options are automatically entered into the input field as tokens (5).

If the user selects items from the filtered option list (3) by clicking or tapping the checkbox, the text entered in input field remains. If the user selects items by clicking or tapping the label, the entered text is cleared.

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If a user tries to enter character combinations that are not in the option list, a visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Tapping the Arrow

Tapping the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Filter bar with multi-combo box (left) --> Full screen multi-combo box selection (right)

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered accordingly using the “starts with” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected one only.

Left: Option list, filtered by user input, Right: Selected options from the list

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Tapping the Remove icon in a token removes it (2). When the user taps on the input field, the list opens to full screen (3). Tapping on the input field sets the focus on it (4) and the mobile device’s keyboard opens (5). When the user types in the first character, the list is filtered by this character (6) using the “starts with” approach. The input field only allows characters to be typed in that match the items in the list.

Left: Multi-combo box with tokens in the input field; Right: List for selection filtered by a character

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

These are the styles of the multi-combo box and their respective states:

Hover highlighting in list

Expanded multiselection

Unselected

Unselected predefined placeholder

Unselected on hover

In focus

Warning

Error

Expanded

Expanded selection

Selected items shown as tokens

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany). Typing into the input field shows all items that start with the search text.

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the multi-combo box. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

Developer Hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multiselection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of an entry closes the option list and creates a token of the selected option. Every entry is accompanied by a checkbox (4) to allow multiselection. Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click or tap the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks or taps the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4), while the typed text remains in the input field. Selected options are automatically entered into the input field as tokens (5).

If the user selects items from the filtered option list (3) by clicking or tapping the checkbox, the text entered in input field remains. If the user selects items by clicking or tapping the label, the entered text is cleared.

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If a user tries to enter character combinations that are not in the option list, a visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Tapping the Arrow

Tapping the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Filter bar with multi-combo box (left) --> Full screen multi-combo box selection (right)

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered accordingly using the “starts with” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected one only.

Left: Option list, filtered by user input, Right: Selected options from the list

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Tapping the Remove icon in a token removes it (2). When the user taps on the input field, the list opens to full screen (3). Tapping on the input field sets the focus on it (4) and the mobile device’s keyboard opens (5). When the user types in the first character, the list is filtered by this character (6) using the “starts with” approach. The input field only allows characters to be typed in that match the items in the list.

Left: Multi-combo box with tokens in the input field. Right: List for selection filtered by a character.

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

These are the styles of the multi-combo box and their respective states:

Hover highlighting in list

Expanded multiselection

Unselected

Unselected predefined placeholder

Unselected on hover

In focus

Warning

Error

Expanded

Expanded selection

Selected items shown as tokens

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany). Typing into the input field shows all items that start with the search text.

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multiselection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of an entry closes the option list and creates a token of the selected option. Every entry is accompanied by a checkbox (4) to allow multiselection. Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click or tap the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks or taps the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4), while the typed text remains in the input field. Selected options are automatically entered into the input field as tokens (5).

If the user selects items from the filtered option list (3) by clicking or tapping the checkbox, the text entered in input field remains. If the user selects items by clicking or tapping the label, the entered text is cleared.

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If a user tries to enter character combinations that are not in the option list, a visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Tapping the Arrow

Tapping the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Left: Filter bar with multi-combo box. Right: Full screen multi-combo box selection.

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered accordingly using the “starts with” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected one only.

Left: Option list, filtered by user input. Right: Selected options from the list.

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Tapping the Remove icon in a token removes it (2). When the user taps on the input field, the list opens to full screen (3). Tapping on the input field sets the focus on it (4) and the mobile device’s keyboard opens (5). When the user types in the first character, the list is filtered by this character (6) using the “starts with” approach. The input field only allows characters to be typed in that match the items in the list.

Left: Multi-combo box with tokens in the input field. Right: List for selection filtered by a character.

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

These are the styles of the multi-combo box and their respective states:

Hover highlighting in list

Expanded multiselection

Unselected

Unselected predefined placeholder

Unselected on hover

In focus

Warning

Error

Expanded

Expanded selection

Selected items shown as tokens

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany). Typing into the input field shows all items that start with the search text.

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Multi-Combo Box

The multi-combo box control is commonly used to enable users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to open the list of available options. The select options in the list have checkboxes that permit multiselection.

Usage

Use the multi-combo box if:

The user needs to select one or more options from a long list of options (maximum of approximately 200).
The values of the option list contain secondary information that does not need to be displayed right away.

Do not use the multi-combo box if:

The user needs to choose between two options, such as ON or OFF and YES or NO. In this case, consider using a switch control instead.
You need to display more than one attribute. In this case, consider using the select dialog or value help dialog instead.
The user needs to search on multiple attributes. In this case, consider using the select dialog or value help dialog instead.
Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using checkboxes instead.

Responsiveness

The multi-combo box is optimized for keyboard and mouse interaction.

Size S

Filter bar with multi-combo box - Size S

Option list in full screen - Size S

Size M

Filter bar with multi-combo box - Size M

Size L

Filter bar with multi-combo box - Size L

Components

Input Field

The input field (2) can display a placeholder text (6) when it’s empty, or a token (1) if a value is selected.

Dropdown Trigger

The dropdown button (3) collapses and expands the dropdown list.

Option List

The option list (7) contains a list of selectable options (5). Clicking the label of an entry closes the option list and creates a token of the selected option. Every entry is accompanied by a checkbox (4) to allow multiselection. Clicking a checkbox creates a token. The option list remains open.

Components of the multi-combo box

Behavior and Interaction

Select a Value

There are three ways to select an item from the list:

Tick the checkbox (option list remains open).
Click or tap the label of a select option (option list is closed).
Use the keyboard (spacebar or Enter).

The user clicks or taps the input field to place the cursor in the field (1). Clicking the arrow displays the list (2). As the user types into the input field, the list is filtered accordingly (3). The up and down arrows move the focus within the list (4). Selected options are automatically entered into the input field as tokens (5).

Input Field

Any character in the input field acts as a filter for the option list. The input field only allows users to type text that matches the items in the list. If a user tries to enter character combinations that are not in the option list, a visual feedback is provided to indicate that the combination of characters is invalid, while the input field suppresses the characters entered.

Behavior - Sizes M and L

Choose from Option List

The option list displays all the available items that the user can choose from. Clicking the arrow opens the option list below the field. If there is not enough space to display the dropdown list below the field, it is displayed above the field instead.

Behavior for Mobile Devices

The following sections describe how the multi-combo box interacts on mobile devices.

Tapping the Arrow

Tapping the arrow opens the option list in a full screen dialog (1) with a title displayed in the header (2). The Close button (3) closes the dialog and cancels any selection changes in the option list. Clicking the label of an entry (4) closes the option list and creates a token of the selected option. By selecting a checkbox (5), the option list remains open and allows multi-selection. The OK button (6) takes over the selection and closes the dialog.

Left: Filter bar with multi-combo box. Right: Full screen multi-combo box selection.

Developer Hint

The title of the full-screen dialog could be customized by adding a label as ariaLabelledBy to the multi-combo box. If no label is associated with the multi-combo box, the default title “Select” is set.

As the user types into the input field (7), the list is filtered accordingly using the “starts with” approach. Pressing the button next to the input field (8) toggles the view between all options and the selected one only.

Left: Option list, filtered by user input. Right: Selected options from the list.

Input Field on Collapsed List

If items have already been selected, the input field remains functional and the tokens remain visible (1). Tapping the Remove icon in a token removes it (2). When the user taps on the input field, the list opens to full screen (3). Tapping on the input field sets the focus on it (4) and the mobile device’s keyboard opens (5). When the user types in the first character, the list is filtered by this character (6) using the “starts with” approach. The input field only allows characters to be typed in that match the items in the list.

Left: Multi-combo box with tokens in the input field. Right: List for selection filtered by a character.

Multiple Selected Items

Not all the selected tokens can be displayed at the same time because the space is limited to the size of the input field (6). Swiping to the side scrolls horizontally to reveal a cropped token (7).

Swiping to display tokens

Copying and Pasting Data from a Spreadsheet or Text File

The control for the multi-combo box can handle paste actions containing, for example, multiple items that have been selected in a column of a spreadsheet or text file. The user simply selects an entire column in the spreadsheet and copies it. When items are entered into the multi-combo box, the user just pastes them from the clipboard and each item is then represented as a token. Only items that are part of the list are displayed as tokens.

Information

For information on how to manage leading and trailing whitespace (blanks) when copying and pasting text into input controls, please see removing leading and trailing whitespace.

Styles

These are the styles of the multi-combo box and their respective states:

Unselected

Unselected predefined placeholder

Unselected on hover

In focus

Warning

Error

Expanded

Expanded selection

Expanded multiselection

Selected items shown as tokens

Hover highlighting in list

Guidelines

Label

The multi-combo box control can be displayed with or without a label. If the field is attached to another field, you don’t need to define a second label. For more information about labels in SAP Fiori, see the label guidelines.

Placeholder

Don’t use the placeholder attribute as an alternative to a label. This is important because the placeholder text will be overwritten as soon as the form is filled out. Labels are necessary because they indicate the meaning of the form fields if the placeholders are no longer visible. Show a placeholder only if the user needs a hint about what data to enter. Don’t repeat the content of the label. A hint could be a sample value or a brief description of the expected format. For more information about how to use the placeholder, see input field.

Option List

Keep the label of an entry in the select option list as short as possible because the list uses single lines only. Values that are too long may be truncated. If you need to indicate that none of the selection options are selected, show a blank input field. Define a default selection whenever possible. The multi-combo box cannot display columns. If you want to show two values in the option list, show the leading information first, followed by the secondary information in parentheses, such as Walldorf (Germany). Typing into the input field shows all items that start with the search text.

Sorting

The option list contains all available items that the user can choose from. Choose one of the following styles depending on how you want the content to be arranged:

Logical: Sort items into a meaningful order. Group related options together and show the most common options first followed by less common options.

Logical multi-combo box

Alphabetical: Sort currencies, names, and so on into alphabetical order. We recommend this for lists with more than eight items.

Alphabetical multi-combo box

Numeric: Sort numeric values into a sequential order with the lowest number first.

Numeric multi-combo box

Chronological: Sort time-related information into chronological order with the most recent first (if applicable).

Chronological multi-combo box

Width

You can adjust the width of the option list to some extent. The multi-combo box control is usually used in forms, where the width is determined by the form element or container in which it is embedded. Therefore, we don’t recommend defining a fixed width, but rather working with proper layout containers such as the form, simple form, or responsive grid layout, and with the layout data property, where the width is defined. If you need to restrict the width to a defined value, set the width accordingly. Keep in mind that there’s no horizontal scrolling in the option list. Entries that are too long are truncated and users won’t be able to read them.

Information

If localized text isn’t an issue, such as with currency codes, use a smaller width.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Combo Box (guidelines)
Select (guidelines)
Input Field (guidelines)
Form (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)
Toolbar (guidelines)
Switch (guidelines)

Implementation

- Multi-Combo Box (SAPUI5 samples)
- Multi-Combo Box (SAPUI5 API reference)

Range Slider

A range slider is a user interface control that enables the user to select a value range within a predefined numerical interval.

Range slider

Usage

Use the range slider if you want to select a value range within a predefined numerical interval. If you want to specify only a single value within a predefined numerical interval, use the slider instead.

Responsiveness

The range slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control. The range slider supports the cozy and compact form factors.

Types

Only a horizontal range slider is available.

Components

The range slider consists of:

Progress line
Minimum and maximum value
Grips
Tooltips or input fields

Range slider components

Behavior and Interaction

Changing Values

If the range slider is editable, the hand cursor appears when hovering over the range slider with the mouse. A tooltip also appears when hovering, displaying the current values of each grip. The grips move together with the corresponding tooltips.

The user can change the value range on the slider in two ways:

By using drag and drop to adjust the grips
By clicking the bar outside the value range. The corresponding grip then moves to the new position.

The grips can be moved with or without increments based on the predefined steps.

Range slider on hover

Range Slider with Input Fields

The range slider can be used with input fields instead of tooltips.

Range slider with input fields

Moving the Entire Range

Users can move the entire value range by dragging and dropping the progress line.

Range slider - Moving the entire range

Equal Values

The grips of the range slider can be positioned on the same value.

Range slider with equal values

Overlapping

The grips of the range slider can be moved across each other. The minimum can become the maximum, and vice versa.

Tick Marks

You can apply tick marks to the range slider. The tick marks are related to the step property. For example, if you have a range from 1 to 100 and a step of 10, the range slider will have 11 tick marks. The tick marks are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Range slider with tick marks

Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Range slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Range slider with custom values as labels

Developer Hint

In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Properties

The step property must be positive. If a negative number is provided, the default value 1 is used instead.
The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and the maximum value to 100 by default.
The width of the control can be provided in percentage (%), em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.
The range property determines the range in which the user can select values. If the value is lower/higher than the allowed minimum/maximum, a warning message is displayed.
The inputsAsTooltips property indicates whether input fields are being used as tooltips for the grips.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Slider (guidelines)
Input Field (guidelines)

Implementation

Range Slider (SAPUI5 samples)
Range Slider (SAPUI5 API reference)

Slider

A slider is a control that enables the user to adjust single values within a specified numerical range.

Slider in an input list item

Usage

Use the slider to change values with graphical support.

Responsiveness

The slider itself is not responsive. It adjusts to the responsiveness of its parent container by recalculating and resizing the width of the control.

The slider supports the cozy and compact form factors. The compact form factor is used for apps that run on devices operated by a mouse and keyboard.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

If the slider is editable, the hand cursor appears when the user hovers over the grip.

The user can change the slider setting in two ways:

By using drag and drop to adjust the grip
By clicking the bar. The grip then moves to this new position.

The grip can be moved with or without increments based on the predefined steps.

Changing the value

Slider with Text Fields

The slider can be used with text fields instead of tooltips. In this case, the value of the grip is displayed.

Slider with text fields

Slider with Input Fields

The slider can be used with input fields instead of text fields. This allows the user to enter a specific value.

Slider with input fields

Slider with Tick Marks

You can apply tick marks to the slider. The tick marks are related to the step property, and are responsive. If the distance between 2 tick marks is less than 8 px, all tick marks except for the first and last disappear.

Slider with tick marks

Slider with Tick Marks and Labels

If tick marks are set, you can define labels for the tick marks. The labels are displayed below the tick marks and show the corresponding value of the tick mark. The labels must always be numbers, and must never overlap. You can also define labels only for specific tick marks if you don’t need a label for every tick mark on the slider. The application developer is responsible for defining a reasonable set of tick marks.

If there is not enough horizontal space to display all the labels, a responsive mechanism is activated. The first and the last label are always visible.

Slider with tick marks and labels

Custom Values

You can define custom values as labels. This can be useful if your scenario requires descriptive intervals, such as as dates. Always keep the values as short and meaningful as possible.

Slider with custom values as labels

Developer Hint

In order to use custom scales in a slider, you must map them to the floats for the slider scale.

Styles

The slider can be shown with or without a progress bar. By default, the progress bar is shown.

Examples

Slider without progress bar

Slider with progress bar

Properties

The step property must be positive. If a negative number is provided, the default value 1 is used instead.
The minimum, maximum, and value properties can be decimals (float values). The slider automatically sets the minimum value to 0 and maximum value to 100 by default.
The width of the control can be provided in %, em, px, and all possible CSS units. The slider automatically sets the width of the slider to 100% by default.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Text (guidelines)
Input Field (guidelines)

Implementation

Slider (SAPUI5 samples)
Slider (SAPUI5 API reference)

Status Indicator

The status indicator uses a filled shape to visualize a single value. Unlike the progress indicator or the radial micro chart, the indicator provides the user with a meaningful association through its use of icons.

Selection of status indicators

Usage

Use the status indicator if:

You need to display a single value with an icon that describes its context.
You need to display a single value that can be updated in real time without reloading the page.

Do not use the status indicator if:

You need to display a single value within a table. Use the progress indicator or radial micro chart instead.
You need to show a rating. Use the rating indicator instead.
The status indicator does not provide the user with any meaningful information and would be for decoration only.

Embedding the Status Indicator

The status indicator can be embedded in other controls, including but not limited to the following:

Status Indicator Embedded in Other Controls

Responsiveness

The status indicator provides four different sizes: small (size S), medium (size M), large (size L), and extra-large (size XL).

For the small size, the partial fill is replaced by a fully-filled shape that can only indicate the semantic per threshold reached.

Predefined Sizes of the Status Indicator (S, M, L, XL)

Layout

A status indicator can consist of a scalable vector graphics (SVG) shape and additional information, such as a label. The status indicator can be configured as a shape only (default), or as a shape with a fixed label.

Shape Only

By default, the status indicator consists of a single shape. We recommend using this type of status indicator when you need to display a fraction of a value, rather than a specific value.

Status indicator - Shape only

Shape with a Fixed Label

This type of status indicator includes not only a shape, but also a label that uses semantic colors defined for the the value thresholds of the status indicator. In addition, you can switch between different alignment options, such as left, right, top, or bottom. We recommended using this type of status indicator when the user needs to see the exact value.

Status indicator - Shape and label

Types

Linear Fill

Most shapes can be filled linearly. You can set the shape to be filled from the left, right, top, or bottom, or define a specific angle for filling.

Status indicator with linear fill

Circular Fill

For round shapes, you can use the circular fill.

Status indicator with circular fill

Filling Sequence

The sequential fill option is useful when the shape consists of multiple parts. You can fill the parts sequentially one by one, or set your own filling order.

Status indicator with filling sequence

Grouping

You can group several shapes together and decide how the filling should be orchestrated among the shapes in this group.

Status indicator grouping

Thresholds

You can set one or more thresholds for each status indicator and assign a color to each threshold. The color changes when a threshold has been exceeded. Only use thresholds and semantic colors if they are meaningful to the user. Do not use them for decoration.

Status indicator tresholds

Behavior and Interaction

You can define a click event for the status indicator. If the status indicators are grouped, you can define a click event for each status indicator or for the entire group.

Information

When setting a click event for a non-filled shape, we recommend using a darker background color to emphasize that the shape is clickable and not disabled.

Guidelines

Shape Definition

You can download the predefined shapes or create your own custom shapes. For more information on how to create custom shapes correctly, see the API documentation.

Developer Hint

Only circle, rectangle, and path tags are supported inside the SVG file.

Animation Duration

Shape animation follows the motion design principles, with a maximum duration of 250 ms (small moves).

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Radial Micro Chart (guidelines)
Progress Indicator (guidelines)
Micro Process Flow (guidelines)
Motion Design (guidelines)

Implementation

Status Indicator (SAPUI5 sample)
Status Indicator (SAPUI5 API reference)
Download Predefined Shapes (ZIP file)

Menu Button

Unlike a regular button, the menu button features an expand icon that triggers a dropdown menu (sap.ui.unified.Menu). The menu button was introduced to address numerous limitations of the action sheet. By default, the menu is positioned below the button, but it can also be displayed above if there is not enough space.

Usage

Use the menu button if:

You need a menu that provides more than one option. Wherever possible, always use the menu button instead of the action sheet, as it offers more options.

Do not use the menu button if:

The menu provides only one option. In this case, consider using a button instead.
It’s important that the user keeps the context on a phone, and you have only a few actions. In this case, use the action sheet instead.

Responsiveness

On smartphones (size S), the menu opens in a full screen dialog. The button label becomes the title of the dialog. The footer contains a Cancel button. Navigation is available with a Back button.

Menu button – Size S

On tablet and desktop devices (Size M/L), the menu button triggers a cascading dropdown menu.

Menu button, regular and split mode - size M/L

Layout

The menu button consists of a button with a label and an expand icon that indicates a menu.

The button has two different modes:

Regular button mode (default): The menu button appears as a regular button. The user clicks or taps it to open a menu. In regular mode, you can use an icon in front of the label description.

Split button mode: The menu button appears as a split button. The user clicks or taps the button to fire the menu’s default action, and clicking/tapping the arrow opens the menu.

The split button is separated into two areas: the label and the icon. The separator between them signals that the two areas result in different actions. The split button supports the emphasized, positive, and negative states of the regular button. The split button consolidates a set of command variations, especially when one of the commands is used more often.

In split mode, the label depends on the default action. If the default action is displayed with an icon only, all the menu items must contain icons.

For more information about cozy and compact modes, see content density.

Width and Truncation

If no fixed width is set, the width of the button is set automatically, depending on the text and the container. The maximum width of the menu button is 12 rem (192 px).

If the label is very long, the maximum width ensures that the menu button is consistent with the width of the menu.

After reaching the maximum width or the set fixed width, the text truncates.

Text-only menu button in compact mode

Text-only menu button in cozy mode

Icon-only menu button in compact mode

Icon-only menu button in cozy mode

Menu button with truncated text

Types

Regular Menu Button

Regular type (default): The user clicks or taps the button to open the menu.

Split Menu Button

The user clicks or taps the button to fire the default action. Clicking or tapping the arrow icon opens a menu.

Regular menu button

Split menu button

Components

The menu button consists of a button with a label and/or icon and an expanding icon that indicates that a menu is available.

In split mode, the two basic elements – the label and the expanding icon – are separated.

Menu button components

Behavior and Interaction

On Tablets and Desktops

The menu button displays a dropdown menu (sap.ui.unified.Menu) as currently implemented.

If the user clicks/taps the menu button, it displays a dropdown menu.
If the user selects a menu item, the action is triggered and the menu closes.
The menu also closes if the user clicks/taps outside the menu, or if the user clicks/taps the button a second time while the menu is open.
The dropdown menu must be displayed in direct connection to the menu button.
The dropdown menu must be positioned below the menu button by default. If there is not enough space below, you may display it above the menu button.

On Smartphones

The menu opens in a full screen dialog. The button’s label becomes the title of the dialog.

To allow the user to navigate out of the menu, use a Cancel button in the footer.
Items with submenus become navigable. Navigation is similar to that used in a popover (sap.m.MessagePopover), in which a “back” button is provided.
When the dialog is reopened, it starts again at the top level.

Split Button

Clicking/tapping the label area triggers one of two types of behavior, which the app developer can configure individually:

It always triggers the default action set by the app developer. If no default item has been defined, the first item in the menu list becomes the default.
It triggers the last action chosen by the user. Initially, it is the default action until the user makes a different selection which then becomes default. The button label changes accordingly. The button has a fixed size and truncates the text if the menu item is longer (as with the combo box).

Expand Icon

If the user clicks or taps the expand icon, the dropdown menu opens.

Styles

The menu button supports all states of the button (sap.m.button).

Default

Positive (property: type = accept)

Transparent

Negative (property: type = reject)

Ghost

Emphasized

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

No links

Implementation

Menu Button (SAPUI5 samples)
Menu Button (SAPUI5 API reference)
Menu Button Mode (SAPUI5 API reference)
Menu (SAPUI5 samples)

Action Sheet

An action sheet consists of a list of options a user can select from to complete an action. Actions can be clustered if there is not enough space on the screen.

Warning

This control has a number of limitations, which were addressed with the introduction of the menu button. Please use the menu button instead of the action sheet whenever possible.

Usage

Use the action sheet if:

You need an option that provides more than one action.
It is really important that the user stays in context on a phone.
You only have a small number of actions.

The menu provides only one option. In this case, consider using a button instead.
You need to show a hierarchical menu. In this case, use the menu button instead.
Your users would benefit more from a split button, which offers an easily-accessible default action, with the option to include additional actions.

Responsiveness

The action sheet is fully responsive. On smartphones, the actions are displayed as a list inside a dialog. On tablets and desktop devices, the actions are displayed in a popover.

Size S (Smartphone)

Action sheet dialog

Size M (Tablet)

Action sheet popover

Size L (Desktop)

Action sheet popover

Layout

All elements in the action sheet are left-aligned. Actions are always arranged in order of importance, from top to bottom. The Cancel button uses a negative button type and is centered to differentiate it from the other app actions. The cursor/focus area for buttons within the action spans the full width of the action sheet (which in turn depends on the longest button).

Action sheet popover

Components

The following UI elements can be placed in the action sheet:

Button
Icon

Behavior and Interaction

Clicking/Tapping

Depending on the device, a click or tap on the overflow icon (“…”) opens either a popover or a dialog. The user can trigger an action or close the action sheet by clicking or tapping anywhere on the screen. On a smartphone, the dialog can be closed only with the Cancel button.

If the user triggers an action, the action sheet closes automatically and the system provides a message toast.

Guidelines

Never use only icons in the action sheet. Display text only or a combination of icon and text.
On smartphones, provide a Cancel button to enable the user to close the dialog without triggering an action.
Avoid scrolling in actions sheets. If you include too many buttons in an action sheet, users have to scroll to see all the actions in the list. Not only does it take users longer to distinguish between actions, but they also find it difficult to scroll without tapping a button by mistake.

Action sheet dialog

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Button (guidelines)
Icon (guidelines)
Popover (guidelines)
Dialog (guidelines)
Message Toast (guidelines)

Implementation

Action Sheet (SAPUI5 samples)
Action Sheet (SAPUI5 API reference)

Switch

The toggle switch mimics a physical switch that allows users to turn individual settings (such as personalization or display settings) “on” or “off”. The initial state of the control (On or Off) is indicated by the inline label. When users change a switch to On, they expect an instantaneous action as soon as the label appears.

Usage

Use the switch if:

You need to emphasize the On/Off characteristic within a dialog.
You need to clearly show the mode or state that a setting is in.
You need a toggle switch for binary settings when changes become effective immediately after the user changes them. For example, if the user needs to set data transmission or accept/reject business objects.
The change in the setting takes effect instantaneously.

Do not use the switch if:

The user has to choose several options or perform extra steps for changes to become effective. In this case, provide checkboxes to choose options and a Submit or Next button to apply the changes. Also use checkboxes or a list view if the user can select multiple items.
The setting that requires a confirmation action or Submit button before it can take effect. In this case, use a checkbox instead.

Types

The switch provides attributes to customize its appearance.

Default switch

Inline Label

The default type allows custom text input. We recommend that you avoid labels comprising more than 3 letters. Otherwise, the text truncates and loses its meaning.

Default switch with custom label

Inline Icon for Accepting and Rejecting

The Accept and Reject switch type allows you to use the check and cross icons. Do not use other icons in this context.

Accept and Reject switch with icon and color coding

Behavior and Interaction

Switch

The user can switch between two values, such as On and Off.

Styles

Depending on their usage, switches come in different states and markups, but are always active or inactive. The interaction states are as follows:

Switch interaction states

Switch Interaction states - Semantic colors

Guidelines

Replace the On and Off labels if there are more specific labels for the setting. Use any short labels (3–4 characters) that represent binary opposites if they are more appropriate for a particular setting. For example, you might use Show and Hide if the setting is “Show images.”

Do not replace the On or Off label unless you really have to. Use the default labels unless there are other labels that are more specific for the setting.

Do not use labels that are longer than three or four characters. Otherwise, the text becomes truncated and loses its meaning.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Select (guidelines)
Radio Button (guidelines)
Checkbox (guidelines)

Implementation

Switch (SAPUI5 samples)
Switch (SAPUI5 API reference)

Planning Calendar

The planning calendar allows users to see different appointments at the same time and to create new appointments. It allows the user to display appointments for several objects, such as a team calendar, and compare them to each other.

Usage

Use the planning calendar if:

You want to compare objects of the same type with each other over a period of time.
You require responsive behavior.
You have less than 100 lines in the calendar.

Do not use the planning calendar if:

You want to show a calendar for one object and a detailed overview of appointments over a long time interval.
You want to show a complex or graphical representation. In this case, please use the Gantt chart.
You have more than 100 lines in the calendar. In this case, please use the Gantt chart.

Responsiveness

In size S, the control 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 the responsiveness is still working.

Planning calendar - Size L

Planning calendar - Size M

Planning calendar - Size S

Types

You can define what size of interval the calendar should show, and whether multi selection should be possible. Additionally, the row header and the interval appointments are optional.

The control allows multi-select mode to be shown for the list items. This can be used, for example, to delete multiple objects from the view.

An app development team must decide whether to show the planning calendar with or without multi-select mode, or whether users should be able to switch between the two modes. Hiding the interval appointments of every object is optional.

The example opposite shows what the interaction looks like if the user can trigger multi-select mode. When the user clicks or taps the button, a checkbox appears next to each list item and a Select All option is shown. Additional actions can appear or disappear in the calendar toolbar.

The planning calendar can also be used without a row header. In this case, the row header disappears and only the appointments are visible. It can be used to show the calendar of one object. Note that the control was built 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 to smaller size. In this case, the text is cut off rather than truncated.

Switching to Multi-Select Mode

Components

This section describes the various components of the planning calendar.

Parts of the planning calendar

The control consists of different parts:

Toolbar
Header
Calendar view
List item
Row header
Row
Appointment
Interval appointment

1. Toolbar

The toolbar is optional and can contain a title as well as app-specific and generic actions.
If you have actions in the toolbar, we recommend that you use a title to describe the purpose of the planning calendar. For more information, check out the toolbar guideline article.

The generic actions are as follows:

Search
Add Appointment (icon: add)
Add New Contact (icon: add-contact)
Multi-Select Mode (icon: multi-select)
Legend (icon: legend)
Settings (icon: action-settings)
Full Screen (icon: full-screen/exit-full-screen)

2. Header

The calendar header comprises the left part, which includes an optional switch to see the calendar in a different view (day, month, year), and the right part, which contains the calendar view.

3. Calendar view

The calendar view defines the granularity of the appointments. You can decide what kind of views (Hours, Days, Months, 1 Week, 1 Month) are available by using the view switch, and how many values are shown for each view. There is a default value for the number of values shown. App developers can change this value, but they should then ensure that the app is still responsive.

The 1 Week view always renders a full week. It displays seven days on one screen. The start date is always the beginning of the week (depending on the locale). It can be found in the view switch as a default view. When applications have this view available, we strongly recommend setting a different number of days displayed in the Days view (more or less than seven). Otherwise, the user might be confused, as the navigation for the two differs.

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

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.