Archives

Table Personalization Dialog

The table personalization dialog allows you to display and modify table settings. It is a UI pattern that defines column order and visibility.

Usage

Use the table personalization dialog if:

  • You have small tables.
  • You have a manageable number of columns.

Do not use the table personalization dialog if:

  • You have large tables.
  • You have a lot of columns to manage.

For larger tables you can use the P13n dialog (sap.m.P13nDialog) instead.

Responsiveness

On a desktop and tablet, the control appears as a dialog window.

The table personalization dialog should always be displayed in full screen mode on a smartphone device.

Table personalization dialog - Smartphone - Size S
Table personalization dialog - Smartphone - Size S
Table personalization dialog - Tablet - Size M
Table personalization dialog - Tablet - Size M
Table personalization dialog - Desktop - Size L/XL
Table personalization dialog - Desktop - Size L/XL

Layout

Position on the Screen

The dialog always opens in a modal window in the center of the screen.

For smartphones, stretch the dialog to fill the entire screen. For tablet and desktop devices, keep the modal window.

Layout of the Dialog

The table personalization dialog comprises the following five areas:

(1) Header

(2) Toolbar

(3) Subtoolbar

(4) Column list

(5) Footer toolbar

Table personalization dialog – Overview
Table personalization dialog – Overview

Components

The table personalization dialog contains the following sections:

Header

The header displays the dialog title.

Table personalization dialog – Header
Table personalization dialog – Header

Toolbar

The toolbar displays the Move Column Up and Move Column Down buttons and the Search field.

Table personalization dialog – Toolbar
Table personalization dialog – Toolbar

Subtoolbar

The subtoolbar displays the All checkbox for selecting all columns, and an Undo Personalization button.

Table personalization dialog – Subtoolbar
Table personalization dialog – Subtoolbar

Column list

The column list displays the result list of columns. The user can use the search field in the toolbar to filter the selection.

Table personalization dialog – Column list
Table personalization dialog – Column list

Footer toolbar

The footer toolbar displays an OK and a Cancel button.

Table personalization dialog – Footer toolbar
Table personalization dialog – Footer toolbar

Behavior and Interaction

Open the Dialog

To open the table personalization dialog, the user must click on the Personalize button on the right-hand side of the table toolbar.

Table personalization dialog – Table
Table personalization dialog – Table
Table personalization dialog – Open dialog
Table personalization dialog – Open dialog

Show or Hide Columns

To show or hide columns, the user only needs to select or deselect the checkbox of a column (list item).

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show/Hide
Table personalization dialog – Show/Hide

The user can show or hide all columns with just one click. A checkbox on the left-hand side of the subtoolbar enables all list items to be selected or deselected.

(1) Columns are visible in the table.

(2) Columns are hidden in the table.

Table personalization dialog – Show all
Table personalization dialog – Show all
Table personalization dialog – Hide all
Table personalization dialog – Hide all

Move Columns

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

Table personalization dialog – Move buttons
Table personalization dialog – Move buttons

Move Column Up

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Up button to move the column to the left in the table.

  • If the first position has been reached, the Move Column Up button is disabled.
Table personalization dialog – Select
Table personalization dialog – Select
Table personalization dialog – Move Column Up
Table personalization dialog – Move Column Up

Move Column Down

(1) Select a column (by clicking on the list item).

(2) Use the Move Column Down button to move the column to the right in the table.

  • If the last position has been reached, the Move Column Down button is disabled.
Table personalization dialog – Select
Table personalization dialog – Select
Table personalization dialog – Move Column Down
Table personalization dialog – Move Column Down

Search/Filter Columns

A search field in the toolbar on the right-hand side enables columns to be searched/filtered.

Table personalization dialog – Search field
Table personalization dialog – Search field

The user can type any character into the search field to filter the columns to match the input.

Table personalization dialog – Search column
Table personalization dialog – Search column

To reset a search, the user must delete all the characters that have been entered, or simply presses the Cancel button in the search field.

All the columns are shown again in the list.

Table personalization dialog – Search reset
Table personalization dialog – Search reset

Undo Personalization

The Undo Personalization button in the subtoolbar on the right-hand side resets all settings to the initial state.

If the table personalization dialog is used together with variant management, the button resets the changes to the initial state of the selected variant.

Table personalization dialog – Undo
Table personalization dialog – Undo

Confirm/Cancel Changes

The changes are adopted when the user closes the dialog via the OK button.

The Cancel button closes the dialog without adopting the changes.

Table personalization dialog – OK/Cancel
Table personalization dialog – OK/Cancel

Guidelines

Search Behavior

The search is a live search (also known as “search-as-you-type”), which is triggered by each character the user enters or deletes. 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

Implementation

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
Table personalization dialog

View Settings 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 – Sort tab
View settings dialog – Filter tab
View settings dialog – Filter tab
View settings dialog – Group 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.

P13n dialog – Columns tab
P13n dialog – Columns tab

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
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
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
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

Implementation

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 exclusively select one 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 value help 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.

Responsiveness

Size S

Size S
Size S

Size M

Size M
Size M

Size L

Size L
Size L

Components

Title

A descriptive heading (1).

Input Field

The input field (2) can display 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 S
Size M/L
Size M/L

Two-Column Layout

Use the combo box with a two-column layout if you need to display additional information for your 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
Combo box with two-column layout

Behavior and Interaction

Select a Value

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

  1. Select the item directly from the dropdown list.
  2. Type the item into the input field.
  3. 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). Typing into the input field starts filtering the list accordingly; the first value is highlighted and auto-complete suggestions appear 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 option list (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 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. An exception is made when there is not enough space to display the dropdown list. In this case, the list is displayed over the input field.

Selecting a value
Selecting a value

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 – Minimum width
Option list adapts to long entries
Option list adapts to long entries

Mobile Handling

The user can enter text into the input field (supported by auto-completion). When the user clicks or taps the dropdown arrow of the combo box (1), the option list opens in full width (2). Now the user can modify the selected entry by tapping the input field of the combo box. The 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 Close 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
Unselected (predefined placeholder)
Unselected (predefined placeholder)
Unselected (on hover)
Unselected (on hover)
Arrow (on hover)
Arrow (on hover)
Focus
Focus
Warning
Warning
Error
Error
Expanded
Expanded
Auto-complete
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.

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

Implementation

Variant Management

Variants store filter settings which have been defined within the filter bar. The filter settings consist of filter parameters, selection fields and a layout. This control enables the user to load, save, and change variants. In some cases, the table settings are also saved within a variant.

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

Smart variant management saves both filter settings and table layouts. It creates a page variant that includes all the controls. The button is located within the page header bar, and no secondary management is possible on table level.

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.
  • Use smart variant management if the user needs to save the page including the filter settings and table layout.

Responsiveness

Size S (Smartphone)

Variant selection, manage dialog, and save dialog are opened in full screen.

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Size M (Tablet)

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Size L (Desktop)

Variant selection
Variant selection
Manage variants
Manage variants
Save variant
Save variant

Layout

The variant management control is used within the filter bar (next to the page title) and the table toolbar (next to the table title).

Filter Bar

The variant management control is located next to the page title within the page header container and saves the stored filter settings or both filter and table settings.

Variant management within filter bar next to the page title
Variant management within filter bar next to the page title

Table

The variant management control can also store table settings (layout, column visibility, sorting, or grouping) independently of the filter settings.

It is placed as the first item within the table toolbar.

If a title or the variant management control is placed inside a toolbar, you need to apply the following styles:

  • The toolbar height must be set to 3 rem.
  • The toolbar design must be transparent.
  • The title must have the class “sapMH4Fontsize”.
Variant management within table toolbar
Variant management within table toolbar

If the table has a separate title, place the title first.

Variant management with table title
Variant management with table title

Behavior and Interaction

This control allows the user to select, create, update, and delete variants within the filter bar. In the context of a table, this is the table configuration (layout, column visibility, sorting, and grouping).

Selecting a Variant

The control label displays the active variant. When the user selects it, a popover displays all available variants. The currently active variant is highlighted. To load another variant, the user simply selects one from the list.

Variants that have been modified but not saved are marked with an asterisk (*).

Selecting a variant
Selecting a variant

If more than 10 variants exist, a search option is displayed.

Select variant – Search option
Select variant – Search option

The standard variant is the minimum set of variants which is delivered by SAP and cannot be modified or deleted.

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 variant. The Save As function can also be used to duplicate existing variants for later modification.

Manage

This opens a new dialog which allows the user to update and delete existing variants.

Creating – “Save As” Variant

The following options can be set:

Set as Default

The variant that is set to default is selected when the user launches the app.

Execute on Select

If this option is active, the variant is executed immediately. The user does not need to click or tap the ‘Go’ button. This option is often used if small filter changes need to be made before the user finally executes the search.

Save As
Save As

Share

The user can set the Share option to make a variant available to other users.

All variants that are shared by users or delivered by SAP, partners, or key users are available within the manage list and the selection list.

Create As Tile

A tile with the same label as the variant is created on the home page.

You can hide the options Execute on Select and Create as Tile by configuring the control correspondingly.

Information
Note that you must still create the tile even if you select the Create as Tile flag.

Managing – Update/Delete Variant

Within the manage dialog, the user can rename, delete, and change properties of existing variants.

Users can only modify or delete entries if they have the necessary permissions. By default, variants which have been created by the user can also be modified and deleted. Users can also modify and delete entries from other users. This is currently a limitation.

 

Based on the configuration of the variant management control, the following column can be hidden or shown:

  • Execute on Select. (If this control is used in the context of tables, Execute on Select is hidden.)
Manage
Manage

Guidelines

In the context of variants, we recommend that you directly reference the variant with the tile. Use the name of the variant as the tile title. 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.

Enable the option Create as Tile within the Save As dialog if your use case generally requires a tile to be created immediately after the Save As action.  In some scenarios, such as MRP, variants and their respective tiles are created on a weekly basis and then removed.

If the variant has been modified but not yet saved (“dirty state”), ensure that the variant is saved before the tile is created.

Exception

If the variant cannot be referenced directly due to technical limitations, offer the standard tile creation option where only filter parameters and settings are saved within the URL. Do not offer the Create as Tile option within the Save As 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

Implementation

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 L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
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 shown in single-select mode. 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
Switching to multi-select mode

Components

This section describes the various components of the planning calendar.

The control consists of different parts:

  1. Toolbar
  2. Header
  3. Calendar view
  4. List item
  5. Row header
  6. Row
  7. Appointment
  8. Interval appointment
Parts of the planning calendar
Parts of the planning calendar

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.

1 Month view - size S
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. This is useful if users want to view calendars from different countries that have different weekends.

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.

7. Appointment

Appointments enable an icon or picture, a title, and a subtitle to be shown. If appointments appear simultaneously, they are shown under each other.

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, and the app development team must define what happens next.

If the view changes and there are too many small appointments at one time, an aggregation is shown. Aggregations show a number indicating how many appointments are not fully visible in this view. This functionality will be improved in future releases. Otherwise, the click/touch area would be too small.

There are two sizes of appointments – regular and half size. The half-sized appointments can save space, but also note that they do not show a second line for details of the appointment.

8. Interval appointment

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

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, not truncated. However, this should not be an issue because the main use case is to see whether there is a free time slot. Additionally, the user can click or tap the appointment to see the details.

In the Months view, appointments may appear as aggregations due to lack of space for detailed visualization. Aggregations show a number indicating how many appointments are not fully visible in this view.

Users have the possibility to turn the alternating row coloring on or off. By default, the alternating rows option is turned on.

Appointments in the calendar have two sizes: regular appointment and half-size appointment. The exact sizes can be found in the visual specification. The app developer can choose the size that fits the use case, but keep in mind that the half-size appointment shows less information about the appointment.

Users also have the option to hide the interval header and the space that is reserved for it. This option can be included as an icon in the toolbar.

1. Switch

The switch is optional and allows users to switch between different views. For example, a user can get an overview of a whole year by selecting the year view. The average length of appointments and the use case should decide which view is the most useful.

2. Today action

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

3. Back and forward navigation

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

4. Day switch

The day switch is only available if the day view is selected. It enables the user to navigate to a different day.

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
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 current day to open the date picker. When the user selects a day, the picker closes and navigates the user to the selected value.
Navigation flow - Switching a day
Navigation flow - Switching a day

Guidelines

Switching the Row Header

If you want the end user to be able 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 should 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

Implementation

Icon Tab Bar

The icon tab bar comprises a series of tabs that each link to a different content area or view. You can use it for navigation within an object, or as a filter.

There are two key use cases:

  • You want to let users navigate between different object facets in the object details area.
  • You want to let users filter lists, and give them the option of calling up the entire list, or only items with a specific attribute.

In both cases, the user switches between tab pages by clicking or tapping the respective tab.

Usage

Use the icon tab bar if:

  • Your business objects need to show many facets at the same time.
  • You want to allow the user to browse through these facets.
  • You need a prominent or very visual filter on top of a list.
  • You have clear-cut process steps that need to be visualized.

Do not use the icon tab bar if:

  • An object type has only one tab in the entire app.
    In this case, we recommend removing the icon tab bar and placing the content on the same level as the object header. To replace the tab label, add a headline with the same text (for example, Information).

Responsiveness

The icon tab bar stretches horizontally, and soon runs out of space on small screens. It responds to limited space by offering a scrolling mechanism.

Responsiveness - Icon tabs
Responsiveness - Icon tabs
Responsiveness - Text tabs
Responsiveness - Text tabs

Layout

The horizontal layout of the icon tab bar never changes. The tabs always appear side by side. However, there are several types of tab bar to choose from. These are described in detail below.

Types

You can use the icon tab bar control to build the following types of tab bars:

  • Text only
  • Icon tabs
  • Tabs as filters
  • Tabs as process steps

Text Only

The text-only variant is one of the most common types. It allows longer labels, and can also display counters above the text to indicate the number of items on the tab page.

Unlike all other tab variants, the labels do not get truncated. The full text is always shown. As a result, you need to ensure that your labels do not become too long. They should still be easy to read on smaller screens.

If you use text-only tabs, make sure that the property UpperCase is disabled and that you enter the labels in title case (Example: Approval Flow).

Types ─ Text-only without counters
Types ─ Text-only without counters
Types ─ Text-only with inline counters
Types ─ Text-only with inline counters

Counters and Text Tabs

If counters are used, set the property HeaderMode to Inline so the counters appear in brackets after the labels.

Please do not use the old layout that shows the counters on top of the labels (Headermode = Standard).

Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

Icon Tabs

Icon tabs are also common tab types. These round tabs can be populated with any icon from the SAP icon font.

Labels are optional. If you decide to use labels, use them for all tabs. You can use counters as needed.

Types - Icons with counters
Types - Icons with counters

Please note that starting with SAPUI5 version 1.40, you should only use the horizontal type of label (icon and label side by side).

If your labels get truncated, consider using shorter labels or text tabs (without icons), as text tabs cannot get truncated.

Types - Icons with counters and labels
Types - Icons with counters and labels
Types - Icon-only
Types - Icon-only

Tabs as Filters

If you build the tab bar as a filter, it can comprise two parts:

  • An “all” tab on the left (optional)
    This tab shows the total number of items, and describes the type of item (for example, 189 Products).
  • Tabs for specific filters
    Use the tab text to indicate the filter attribute.
    We strongly recommend showing a counter on every tab.
Types - Filter
Types - Filter

Tabs as Process Steps

You can also use the tab bar to depict a process. In this case, each tab stands for one step.

To connect the steps, use the triple-chevron icon ( ) from the SAP icon font (technical name: process).

Types - Process
Types - Process
Developer Hint
When using icons with labels, add a comment in the properties file to make editors and translators aware that space is limited.
Example: Label for icon tab on detail screen. Max 14-16 characters (depending on character width).

Test whether your labels and their translations are displayed in full, and do not get truncated.

Behavior and Interaction

Clicking/Tapping on Tab

To navigate through the views, the user clicks or taps the tabs.

Optional behavior: If the user clicks or taps a tab that’s already open, the container collapses. It opens again when the user clicks any tab.

Use the “expandable” property to specify whether users can collapse the tab container (default = true):

  • Let users collapse the container if there is additional content below the container, and the information inside the container is not always needed.
  • If there is no content below the tab container, set the “expandable” property to false.

The “expandable” property controls the initial state of the container. Do not change the default state (true).

Styles

The two different styles (round tabs and text only) are discussed in the Types section.

In both cases, you can use colors to give users additional orientation.

Information
Do not use colors for decoration only.  Colors should always indicate a status that is relevant to the user.
When using colors, stick to the semantic colors provided by visual design. Do not hard-code color values. Instead, use the CSS extension “Less”.

Only use semantic colors if it is important for users to know that they need to take action (for example, to indicate errors or critical situations requiring action). Otherwise, use the neutral default colors.

This example shows a process where one step is indicating an error. Since the other tabs have neutral colors, it is clear that they do not contain errors. Coloring them green to show that they are OK is unnecessary, and would reduce the severity of the red tab.

Styles - Colors
Styles - Colors

Guidelines

Apply the styles as follows:

  • If you have only a few tabs that can easily be visualized with icons, use the icon-only tabs. If a short description is needed, use icons and labels.
  • If the content cannot easily be identified by an icon, use the text-only tabs. They also allow for longer labels.
  • If you are using the icon tab bar in the object view floorplan, use either icon-only or text-only tabs.
    Icons only:
    Use this option if you have only 4–5 tabs that can be very clearly identified by their icon.
    Text only:
    Use this option if you have more than 4–5 tabs, or if there are no clear icons to represent the content. Set the property HeaderMode to Inline.
Do
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Counters – Inline Layout ('HeaderMode' set to 'Inline')
Don't
Counters – Old Layout ('HeaderMode' set to 'Standard')
Counters – Old Layout ('HeaderMode' set to 'Standard')

If you use icon tabs, ensure the following:

  • The icons clearly identify the content on the tab pages.
  • Each tab has a unique icon. Do not use the same icon more than once.
  • The icons are easily distinguishable.
  • Any icons between tabs (for example, as separators or connectors) are visually very different from the icons on the tabs.
  • Either all or none of the icons have labels.

Implement the focus as follows:

  • By default, show the first tab as open. This is the initial setting provided by the control.
    Note: Technically, you can also override the initial selection. However, this is not recommended.
  • Later on, you can show the tab last selected by the user.

Additional guidelines:

  • Do not display a loading indicator above the tab while the number for the item count is loading.
  • Handle empty tabs as follows:
    • Hide tabs that do not contain any information, and do not allow the user to create content..
    • Show empty tabs that allow users to create content, such as notes or attachments.
  • Only use the tab bars to navigate between tabs. Do not use any other navigation links. For example, do not let users click an item in tab A that takes them to tab B.
    This type of cross-navigation inside a container is confusing, and cannot be handled by the back navigation.

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

Process Flow

The process flow control allows you to show flows of multiple types of objects, such as documents and approvals. Document flows can split into numerous branches, while approval flows are usually straightforward.

Usage

Use the process flow if:

  • You need to display document flows.
  • You need to display approval flows.
  • You need to display other kinds of flows with linear and/or branching paths.

Do not use the process flow if:

  • You want to display the process flow header in combination with something other than the flow map. In this case, use the icon tab bar (style: process) instead.

Responsiveness

The process flow reacts to the size of the container it is put into. It has four zoom levels, with level 1 being the largest and level 4 the smallest. In containers wider than 1024 px, level 2 is chosen automatically. For containers from 600 to 1023 px, level 3 is set, and below 600 px, it is level 4. For more information, see Behavior and Interaction.

Process flow – Size S
Process flow – Size S
Process flow – Size M
Process flow – Size M
Process flow – Size L
Process flow – Size L

Layout

At the top of the control is a bar, with the zoom buttons on the left and the full screen toggle on the right.

Below the bar is the process flow header, which can also be used on its own if the complex visualization of nodes is not required. The header consists of multiple steps, each of which is visualized by a circled icon. Each icon is surrounded by a circular chart to indicate the distribution of statuses per column.

The flow map lies beneath the header. The elements belonging to a certain step are vertically aligned beneath one another. Arrows point to the next (follow-up) element or multiple elements. Dotted arrows pointing to semi-transparent elements indicate planned or pending elements.

In turn, each element comprises different sections:

  1. Header (mandatory) –Wraps twice before truncation.
  2. Status (optional) – With semantic color and icon; can wrap once.
  3. Attribute 1 (optional) – Wraps once before truncation.
  4. Attribute 2 (optional) – Wraps once before truncation.
Layout – Sections
Layout – Sections

Naturally, the header information is mandatory because it is the key identifier of an object. The header should contain a brief but meaningful description and, if necessary, an ID in brackets.

Although the status is optional, an icon appears on an item without a status at the smallest zoom level. When the user zooms out completely, only the status icon remains visible on an item. Without it, the element looks broken and does not provide any information.

There are two options to filter the nodes for certain types or attributes. For simple filtering, you can use a filter button in the toolbar to trigger a filter dialog. For more complex filtering, the filter bar control can be placed on top of the process flow.

Components

The process flow control consists of the process flow header and the flow map.

For better usability, it is highly recommended to add a toolbar with zooming controls (    ).

A full-screen switch is optional and can also be put in the toolbar (  ).

Behavior and Interaction

Navigation and Zoom

User can move the whole flow with the left mouse button held down, just like they would move a street map in a browser.

To zoom in or out, the user can use the mouse wheel or, if implemented, click the respective buttons on the bar on top of the flow line. The zoom is semantic: detailed information is added or removed depending on the zoom level.

If the process flow is wider than the available space, a chevron (< or >) appears on the side where the flow extends beyond the visible area. A number also indicates how many process steps lie outside, such as < 2 or 5 >.

Level 1

Larger elements provide the most space for
textual information. However, fewer elements
fit on the screen.

Zoom in (node)
Zoom in (node)
Zoom in (process flow)
Zoom in (process flow)

Level 2 (automatic preset for screens wider than 1024 px)

The standard size provides the best combination
of content information and overview.

Zoom in – Standard size
Zoom in – Standard size
Zoom in – Standard size
Zoom in – Standard size

Level 3 (automatic preset for screen widths from 600 px to 1023 px)

Elements are reduced to header and status
information to provide a better overview for
large flows.

Zoom in – Elements are reduced to a header and status information
Zoom in – Elements are reduced to a header and status information
Zoom in – Elements are reduced to a header and status information
Zoom in – Elements are reduced to a header and status information

Level 4 (automatic preset for screens below 600 px width)

The smallest zoom level provides a maximum
overview of the flow while the information about
each element is reduced to a status icon.

Zoom in – Element is reduced to a status icon
Zoom in – Element is reduced to a status icon
Zoom in – Elements are reduced to a status icon
Zoom in – Elements are reduced to a status icon

When a node is clicked, applications should provide a popover with additional details about this element. It should give users a deeper insight into the status or, in the event of an issue, a way to solve the problem. From the quick overview, users should be able to navigate to the element’s fact sheet.

If no additional information needs to be displayed, an action sheet can be triggered instead of the popover to allow users to perform actions on the item.

Labels on Connections

Some use cases focus on the connections between the nodes as much as on the nodes themselves. For these cases, we provide labels that can be displayed on each connection which, in turn, provide the user with the necessary information.

If multiple paths overlap, applications need to aggregate the respective labels and show the ‘worst’ status.

Labels
Labels
Process flow – Labels (1)
Process flow – Labels (1)

When the user clicks on an aggregated label, app developers need to provide a popover showing a list of connection paths for the user to select from.

Process flow – Labels (2)
Process flow – Labels (2)

In the popover, the user should now be able to browse through the paths, while the process flow is updated accordingly.

Process flow – Labels (3)
Process flow – Labels (3)

To give the user more information, a Details button needs to be shown in the footer.

The details must be shown in the same popover, and a back button must be offered that allows the user to return to the path overview.

The footer of the details overview can contain up to two actions.

Labels - Process flow
Labels - Process flow

Highlight Path

The feature highlight path allows users to focus on specific nodes and their path through the process flow, for example by highlighting a search or filter result.

Example: A user searches for a specific item inside an order. The nodes containing or exclusively representing this item are highlighted, while the rest of the flow are dimmed.

Highlight path
Highlight path

Business Focus

The business focus is a rarely used feature. It allows applications to put a visual focus on a node that is separate from (and not to be confused with) the selection or keyboard focus.

If, for example, the process flow is used next to another control (such as the timeline), the business focus can be used to highlight a node that corresponds to a selection in the other control:

  1. The timeline shows an automated post “There is an invoicing problem with Item 0815 from Order 4711.”
  2. The user clicks on the post (not onto a specific link).
  3. The respective node in the lane Invoice is highlighted.

If you use the business focus, make sure that only one node is selected at a time.

Business focus
Business focus

Styles

Two visualizations are available for the nodes inside the flow: a specific visualization for documents, and one for general objects (basically everything except documents). App teams can use the FoldedCorners property to choose the type of objects that the process flow represents.

FoldedCorners = true: This style gives the node a “dog ear”, which makes it very recognizable as a document.

FoldedCorners = false (default): This setting has no specific visual style and is therefore suitable for all object types.

The property affects the entire flow; in other words, it cannot be applied solely to individual nodes. Therefore, it should only be set to true if all the nodes represent documents (or document-like objects). If some or all of the elements are better visualized with the general style, FoldedCorners should be set to false.

Styles – FoldedCorners – True
Styles – FoldedCorners – True
Styles – FoldedCorners – False
Styles – FoldedCorners – False

Aggregation

Some flows can be arranged more clearly by using aggregation. Nodes that belong to the same lane (column) can be displayed as a stack by setting the property Type to Aggregated. This means that nodes that would usually be displayed one below the other are shown as a stack of nodes.

The interaction for these stacks is identical to the regular nodes: the control provides a click event that app developers can use to show a popover with more detailed information.

The description on these stacks should be helpful to users, for example, by telling them how many nodes are in the stack. Aggregated amounts can also be shown.

The statuses in the stacks can be heterogeneous. However, it is imperative to show the ‘worst’ status(es) at the top so that users know whether they have to take action.

In the upper example on the right-hand side, the nodes under Delivery and Invoice are shown as stacks instead of individual nodes.
The lower example on the right shows the same stacks when zoomed out (level 4).

Aggregation
Aggregation
Aggregation (zoom)
Aggregation (zoom)

Guidelines

The process flow header is not a substitution for the icon tab bar. For more details, see the Usage section at the top of this article.

Keep the amount of information inside each node to a minimum. Reveal more information via a popover.

Although technically possible, the node titles should not be turned into links. The IsTitleClickable property should be left in its default state (“false”). Titles that the user can click or tap may lead to usability issues. Handle every action or interaction via a popover and/or navigation to a subsequent page.

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

Implementation

Cumulation (Waterfall Chart)

Waterfall charts are used to analyze a cumulative value. They show how the cumulative value changes from an initial state to a final state by representing the accumulation of successive values.

 

Examples

Profit and Loss

The margin is a cumulative value equal to the sum of all revenues (positive) and all costs (negative).

Profit and loss waterfall chart
Profit and loss waterfall chart

Inventory over Time

The stock level is equal to the sum of all incoming stocks (positive) and outgoing stocks (negative).

Stock level over time waterfall chart
Stock level over time waterfall chart

Chart Types

The orientation of the waterfall chart (horizontal or vertical) should follow best practices of the business area from which the application is designed.

Waterfall Chart Without Time Dimension

If the chart does not represent changes over time, use a horizontal waterfall chart with horizontal bars. This way, you will avoid unnecessarily truncating the category labels.

Horizontal waterfall chart
Horizontal waterfall chart

Waterfall Chart with Time Dimension

If the chart represents the change of a cumulative value over time, use a vertical waterfall chart with vertical bars, with the horizontal axis representing the temporal dimension.

For the horizontal axis, you can choose between a categorical axis or a time axis:

  • Choose a categorical axis if you need to display the total and subtotal. But be aware that the dates might be displayed at a 45° angle in the categorical axis, and that you must manage the localization of the date and time by yourself.
Horizontal waterfall chart with categorical time axis
Horizontal waterfall chart with categorical time axis
  • Choose the time axis if you do not need to display the total and subtotal. With the time axis, the dates will be correctly displayed in the horizontal axis and correctly localized. Also, with the time axis, the physical spacing between your data points accurately respects the time scale being displayed, as opposed to just rendering all your data points equidistantly.
Waterfall chart with time axis
Waterfall chart with time axis
  • With the time axis, you can also display multiple measures in the so-called “periodic waterfall chart”. In the periodic waterfall chart, all measures are cumulated for each period.
Periodic waterfall chart
Periodic waterfall chart

Total and Subtotal

Warning
Total and subtotal are not supported when using a time axis.

The initial and the final values are usually represented by an entire column starting from the zero axis. An intermediate total can be added.

Waterfall chart with an intermediate total
Waterfall chart with an intermediate total

You can also add intermediate subtotals that are the sum of previous values.

Waterfall chart with an intermediate subtotal
Waterfall chart with an intermediate subtotal

Colors

Default Colors

By default, the chart use three colors based on the following semantic:
  • Positive values use a color defined by the property: plotArea.dataPoint.color.positive.
  • Negative values use a color defined by the property: plotArea.dataPoint.color.negative
  • Totals use a color defined by the property: plotArea.dataPoint.color.total
By default, these three colors are:
  • Blue (@sapUiChartPaletteSequentialHue1Light1)
  • Green (@sapUiChartPaletteSequentialHue2Light1)
  • Gray (@sapUiChartPaletteSequentialNeutral)

These colors are defined by the sequential palette, but can be customized.

Waterfall chart with default colors
Waterfall chart with default colors

Custom Colors

You can customize the colors in two ways:
  • Change the colors, or
  • Use your own rules.

Changing Colors

The colors color.positive, color.negative and color.total can be changed to any color from the chart palette. The chart will use these three colors based on the rules defined above.

Example: Positive and negative are blue, and total by gray.

Waterfall chart with custom colors
Waterfall chart with custom colors
Example: Positive are green and negative are red. Total is gray.
Waterfall chart with semantic colors
Waterfall chart with semantic colors

Using your Own Rules

You can set any color to any bar based on your own rules. To define the rules, use the property dataPointStyle:rules.

Use dataPointStyle:others to define the colors for all data points that are not covered by the rules. If the color of a data point is not defined, the data point will be displayed with a black color to indicate that no color has been defined.

Example: Direct costs and indirect costs use different shades of green from the sequential palette.
Waterfall chart with colors based on business rules
Waterfall chart with colors based on business rules

Resources

Want to dive deeper? Follow the links below to find out the SAPUI5 implementation.

Elements and Controls

Implementation

Interactive Chart

The interactive chart is used for visual-based filtering in the visual filter bar (VFB) within the analytical list page (ALP). It allows the user to filter by categories, time periods, or by parts of a whole.

Usage

Use the interactive chart if:

  • You want to give the user the possibility to visually filter data in the analytical list page.
  • You want the user to gain insights before filtering large datasets with the visual filter bar.

Do not use the interactive chart if:

  • You want to visualize data without using it for filtering.
  • You are not using the visual filter bar.
  • You want to visualize data for more complex scenarios. In this case, use the VizFrame chart instead.

Responsiveness

The interactive chart is fully responsive and supports both cozy and compact content density.

Types

There are three types of interactive charts currently available:

Interactive Bar Chart

Filter by categorical data
Filter by categorical data

Interactive Line Chart

Filter large sets of data by time period
Filter large sets of data by time period

Interactive Donut Chart

Filter by parts of a whole
Filter by parts of a whole

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

Implementation

Interactive Line Chart

The interactive line chart is a type of interactive chart used for visual-based filtering in the visual filter bar (VFB) within the analytical list page (ALP).

It allows the user filter large sets of data by time period. The user can see both the time period and the measure at the same time, where the period is always the horizontal (X) axis of the chart.

Usage

Use the interactive line chart if:

  • You want to give the user the possibility to visually filter data in the analytical list page.
  • You want the user to gain insights before filtering large data sets with the visual filter bar.
  • You want to measure trends and changes over time when filtering.

Do not use the interactive line chart if:

  • You want to visualize data without using it for filtering.
  • You are not using the visual filter bar.
  • You have scenarios that do not depict time periods.
  • You want to visualize data for more complex scenarios. In this case, use the VizFrame chart instead.

Responsiveness

The interactive chart is fully responsive and supports both cozy and compact content density.

Layout

The interactive line chart consists of two mandatory areas – a filter label and an area containing the measure and visualization of the chart. The control itself doesn’t contain an axis title.

Interactive line chart - Layout
Interactive line chart - Layout

Filter Labels

The filter labels contain the filter criteria and are left-aligned. They may be truncated if not enough space is available. To avoid this, we highly recommend using the short format for time-related filter labels. For example:

  • Year: 2017
  • Half Year: H1, H2
  • Months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
  • Quarters: Q1, Q2, Q3, Q4
  • Week: W1-W52
  • Weekdays: Mon, Tue, Wed, Thu, Fri, Sat, Sun
  • Days: Jan 1, Jan 2 … Dec 31

Measure and Visualization

The interactive line chart can display percentage and actual values as a measure but never a mix of both at the same time. Always display measures using one decimal point. Measures should always be visible and never truncated.

The interactive line chart does not support coloring and the default color of the bars should not be customized.

Do
Do: Display measures in either actual or percentage values
Do: Display measures in either actual or percentage values
Don't
Do not: Display a mix of both actual and percentage values
Do not: Display a mix of both actual and percentage values

The interactive line chart can display positive, negative and mixed (positive and negative) measure values.

The time axis line serves as the zero line, which can be displayed accordingly to indicate different relations between the positive and negative values.

Exame displaying positive and negative measure values
Exame displaying positive and negative measure values

Behavior and Interaction

Selecting and deselecting a section resembles toggle-like behavior. If the user clicks on a selected section, it becomes deselected and vice versa. By default, the interactive line chart supports multiple selection, allowing the user to select more than one filter value.

Interactive Line Chart - Interaction
Interactive Line Chart - Interaction

Guidelines

Use the interactive line chart in the visual filter bar if you would like to have a filter for the highest or lowest values of a filter dimension. For example, to filter for the highest or lowest margin, revenue, or cost related to a project.

In the visual filter bar, the interactive line chart only displays the last or first six data points (such as last six days, last six months, and so on).

In general:

  • You should display the measure labels with one decimal point.
  • Do not display an axis title.
  • Do not display any scrollbars.

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

Implementation

Interactive Donut Chart

The interactive donut chart is a type of interactive chart used for visual-based filtering in the visual filter bar (VFB) within the analytical list page (ALP).

The interactive donut chart allows the user to filter by parts of a whole – depending on the sorting this would be the biggest or the smallest filter values by measure.

Usage

Use the interactive donut chart if:

  • You want to give the user the possibility to visually filter data in the analytical list page.
  • You want the user to gain insights before filtering large data sets with the visual filter bar.

Do not use the interactive donut chart if:

  • You want to visualize data without using it for filtering.
  • You are not using the visual filter bar.
  • You want to visualize data for more complex scenarios. In this case, use the VizFrame chart instead.

Responsiveness

The interactive chart is fully responsive and supports both cozy and compact content density.

Layout

The interactive donut chart consists of two mandatory areas – a visualization and an area containing the filter label and measure of the chart. The control itself doesn’t contain an axis title.

 

Interactive donut chart - layout
Interactive donut chart - layout

Filter Labels

The filter labels are left-aligned and may be truncated if not enough space is available.

Measure and Visualization

The interactive donut chart can display percentage and actual values as a measure but never a mix of both at the same time. Always display measures using one decimal point. Measures should always be visible and never truncated.

The interactive donut chart does not support coloring and the default color of the bars should not be customized.

Both areas (visualization and filter label/measure) should be aligned and be displayed at the same height.

The visualization is always displayed on the left side, and should not appear in different position relative to the labels, such as above or below them.

Do
Do: Both areas (visualization and filter label and measure) are aligned and shown at the same height
Do: Both areas (visualization and filter label and measure) are aligned and shown at the same height
Don't
Do not: Both areas (visualization and filter label and measure) are not aligned
Do not: Both areas (visualization and filter label and measure) are not aligned

The interactive donut chart cannot display a mix of positive and negative measure values. It should be used for displaying only positive or only negative values (parts of a whole).

Behavior and Interaction

Selecting and deselecting a section resembles toggle-like behavior. If the user clicks on a selected section, it becomes deselected and vice versa. By default, the interactive donut chart supports multiple selection, allowing the user to select more than one filter value.

Interactive donut chart - Interaction
Interactive donut chart - Interaction

Guidelines

Use the interactive donut chart in the visual filter bar if you would like to have a filter for the highest or lowest values of a filter dimension. For example, to filter for the highest or lowest margin, revenue, or cost related to a project.

Within the visual filter bar, only the two biggest or smallest values (depending on the sorting order) are shown, while the rest are aggregated into the “Others” section.

In general:

  • You should display the measure labels using one decimal point.
  • Do not display an axis title.
  • Do not display any scrollbars.

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

Implementation

Interactive Bar Chart

The interactive bar chart is a type of interactive chart used for visual-based filtering in the visual filter bar (VFB) within the analytical list page (ALP).

It allows the user filter by categorical data. Depending on how the data is sorted, this would be the biggest or the smallest filter values by measure.

Usage

Use the interactive bar chart if:

  • You want to give the user the possibility to visually filter data in the analytical list page.
  • You want the user to gain insights before filtering large data sets with the visual filter bar.

Do not use the interactive bar chart if:

  • You want to visualize data without using it for filtering.
  • You are not using the visual filter bar.
  • You want to visualize data for more complex scenarios. In this case, use the VizFrame chart instead.

Responsiveness

The interactive chart is fully responsive and supports both cozy and compact content density.

Layout

The interactive bar chart consists of two mandatory areas – a filter label and an area containing the measure and visualization of the chart. The control itself does not contain an axis title.

Interactive bar chart - layout
Interactive bar chart - layout

Filter Labels

The filter labels are left-aligned and may be truncated if not enough space is available.

Measure and Visualization

The interactive bar chart can display percentage and actual values as a measure but never a mix of both at the same time. Always display measures using one decimal point. Measures should always be visible and never truncated.

The interactive bar chart does not support coloring and the default color of the bars should not be customized.

Do
Do: Display measures as actual or percentage values
Do: Display measures as actual or percentage values
Don't
Do not: Display a mix of both actual and percentage values
Do not: Display a mix of both actual and percentage values

The interactive bar chart can display positive, negative, and mixed (positive and negative) measure values.

Display of positive and negative measure values
Display of positive and negative measure values

Behavior and Interaction

Selecting and deselecting of a bar is toggle-like behavior – if the user clicks on a selected bar it becomes deselected and vice versa. By default the Interactive Bar Chart supports multiple selection – the user can select more then one Filter Value.

Interactive Bar Chart - Interaction
Interactive Bar Chart - Interaction

Guidelines

Use the interactive bar chart in the visual filter bar if you would like to have a filter for the highest or lowest values of a filter dimension. For example, to filter for the highest or lowest margin, revenue, or cost related to a project.

The interactive bar chart used in the visual filter bar contains maximum of three filter values with their corresponding measures.

In general:

  • You should display the measure labels with one decimal point.
  • Do not display an axis title.
  • Do not display any scrollbars.

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

Implementation

Analytical Card

The analytical card is used for data visualization. It consist of two areas – a header area (either a standard header or a KPI header) and a chart area that displays a visual representation of the data. It is a single object card and does not contain a footer area. The analytical card can only be used in the overview page (OVP).

Responsiveness

The analytical card has a uniform horizontal width of either 20 or 25 rem, depending on the screen size. The vertical height is flexible. The VizFrame charts within the cards are fully responsive.

Header Area

There are two header types that could be used with the analytical card depending on the use case:

Standard Header

  • Title (mandatory): The title symbolizes the most important information. We recommend using a single-line text, but it is possible to wrap the title to two lines.
  • Subtitle (optional): The subtitle can be wrapped up to two rows and will get truncated at the end of the second line. If the subtitle contains multiple qualifiers, separate them with comma. Do not repeat the chart title here.
Standard header
Standard header

KPI Header

  • Title (mandatory): The title symbolizes the most important information. We recommend using a single-line text, but it is possible to wrap the title to two lines.
  • Subtitle (mandatory): The subtitle can be wrapped up to two rows and will get truncated at the end of the second line. The unit of measure is shown at the end of the subtitle. For this reason, we recommend keeping the subtitle short and within one line. If the subtitle contains multiple qualifiers, separate them with comma. Do not repeat the chart title here.
  • KPI area, containing the following elements:
    • Trend arrow (optional)
    • KPI value (mandatory) – The KPI value uses semantic colors
    • Percentage symbol (optional)
    • Value selection information (optional) – Manually-entered text to provide a better description of the key value (for example, Number of Products). It can be used in case the sorting information and the filters do not provide enough information to properly describe the value. This text will become truncated after one line.
    • Sorting information (mandatory) – Describes the KPI/value.
    • Filters (optional) – Can be modified to show meaningful text.
    • Target and deviation (both mandatory) – They could be a relative or absolute value.
KPI header
KPI header

Types

There are eight chart types currently supported by the analytical card:

 

Information
You can find additional information about the different chart types, as well as tips for choosing the correct chart type, in the following articles:

Line Chart

In general, the line chart is the most efficient chart for showing the evolution of a trend over a period of time.

  • Avoid showing more than four lines in the same card.
  • When showing more than one line in the chart, different units should not be displayed. All the lines should use the same unit, such as “Euro”.

Use the line chart if…

  • You want to emphasize the evolution of a trend over a period of time.
  • You want to visualize data that contains an intrinsic order, such as age, a range, or a rating (but excluding time). In this case, there is an idea of a progression or trend, and the best way to represent these values is to use the horizontal axis.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Do not use the line chart if…

  • You want to emphasize the values themselves. Use a column chart instead.
  • The data does not contain an intrinsic order.

Analytical card with line chart and view switch
Analytical card with line chart and view switch

Bubble Chart

A bubble chart displays the correlation between three sets of numerical values. One set is represented in the horizontal axis, another set is represented in the vertical axis, and the third set is encoded in the size of the bubbles.

We recommend showing only one or two series. Because series are represented by specific bubble colors, having too many series/colors can make the chart hard to read.

The sizes of the bubbles are determined by the values in the third data series. The measure that is represented by the bubble size is defined below the chart.

Color

  • If the goal is to isolate outliers within a cloud of other bubbles, use the same color for all bubbles.
  • If the goal is to group bubbles that have the same characteristic, use one color per group. Warning: Too many colors can make the chart hard to read.
  • If the goal is to compare bubbles individually, then use one color per bubble. Only use this option if there are very few bubbles.

Use the bubble chart if…

  • You need a rough approximation of the values encoded in the bubble size.
  • You want to represent data with three dimensions on a 2D chart.
  • You want to compare and show the relationships between labeled/categorized circles, by the use of positioning and proportions.
  • You want to display the correlation between three sets of numerical values.

Do not use the bubble chart if…

  • You need to represent information only with two dimensions.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with bubble chart
Analytical card with bubble chart

Column Chart

Column charts are used to compare multiple values over time or over values containing an intrinsic order (such as age).

Columns are clustered side-by-side along the horizontal axis and are color-coded by series.

  • We recommend using no more than two series and a maximum of four category items.
  • If you want to show the trend over time of two series, you can use the line chart with two lines instead of two series of columns.

Use the column chart if…

  • Category items represent a time series. The natural orientation for time is from left to right.
  • Category items contain an intrinsic order. For example, age, range, and ranking.
  • You want to emphasize the values themselves rather than the trends.

Do not use the column chart if…

  • Your data is not related to a time category or to a category with an intrinsic order.
  • You want the emphasis to fall on the trend. Use the line chart instead.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

For more detailed information, see column chart.

Analytical card with column chart
Analytical card with column chart

Stacked Column Chart

This type of visualization depicts items stacked on top of one other in columns, with the item categories differentiated by colored bars or strips.

This chart works only for time series and categories with an intrinsic order.

Use the stacked column chart if…

  • You want to display variation of the sum of measures over a period of time.
  • The sum of the values is as important as the individual items.

Do not use the stacked column chart if…

  • Accuracy or comparisons are of primary importance. In this case, a line graph might be the better option.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with stacked column chart
Analytical card with stacked column chart

Vertical Bullet Chart

The bullet chart is used to compare a primary value to a secondary over time or over a category containing an intrinsic order, such as age, range, or ranking.

The bullet chart supports primary values, comparison values and additional values. For more information, see bullet chart.

Use the bullet chart if…

  • You want to compare a primary value to a secondary value using a reference point. For example, if you want to compare actual and planned costs per quarter.
  • The category items represent a time series. The natural orientation for time is from left to right.
  • The category items contain an intrinsic order.

Do not use the bullet chart if…

  • Your data does not contain an intrinsic order.
  • You have only one series of data.
  • There is no data series that act as a reference point for the other data series.
Analytical card with bullet chart
Analytical card with bullet chart

Donut Chart

The donut chart is used to represent parts of a whole, and the whole should always represent 100%. The data is displayed in rings, where each ring represents a data series.

We recommend using a maximum of four sections in the donut chart. If there are more than four sections in the chart, the ‘Others’ section can be used. It merges several sections into one. The number of all sections included in ‘Others’ is mentioned in the legend item.

The donut chart provides the ability to display percentage next to each section in the chart.

Use the donut chart if…

  • You want to visualize the part to whole as a percentage.

  • You have one or more category items that you want to plot.

Do not use the donut chart if…

  • You want to plot negative or zero values.
  • You have more than four categories or sections.
  • You want to compare data over time. You can use the column chart, line chart, stacked column chart, or bullet chart instead.
Analytical card with donut chart
Analytical card with donut chart

Combined Column and Line Chart

Combined column and line charts are used to compare two sets of values over time or over a category containing an intrinsic order, such as age, range, or ranking.

You could also use a column chart or a line chart for that, but using a combined column and line chart is the better choice if you want to clearly distinguish between the two sets of values, or if the values represent different measures, such as revenue and profit.

Use the combined column and line chart if…

  • You want to compare values in different categories.

  • You want to give a clear view of which category is higher or lower.

  • You want to use more than one measure.

Do not use the combined column and line chart if…

  • The combination data between line and column is not logical.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with combined column and line chart
Analytical card with combined column and line chart

Scatter Plot Chart

A scatter plot chart is a type of chart that displays the correlation between two sets of numerical values. The data is displayed as a set of points plotted on a horizontal and vertical axis.

We recommend showing only one or two series. Because bubbles in a series are color-coded, having too many series/bubbles can make the chart hard to read.

Use the scatter plot chart if…

  • You want to show the correlation between two sets of numerical values (for example, the correlation between age and income).

Do not use the scatter plot chart if…

  • You want to show the correlation between three sets of numerical values. Use the bubble chart instead.
Analytical card with scatter plot chart
Analytical card with scatter plot chart

Behavior and Interaction

The entire header area of the card is selectable. It serves as navigation to the specific app or view from which the card content originates. If the application needs to show detailed information about a specific data point, the single selection mode can be used. It is up to the app developer to provide meaningful navigation.  For example, clicking/tapping on a section from the donut chart can navigate the user to an object page providing more information.

There are two selection modes for the charts: single selection and no selection. Clicking or tapping a blank area on the chart does not trigger any action.

Single Selection

In the single selection mode, clicking or tapping a data point selects the data point and navigates to a more detailed screen.

No Selection

In this mode, data points cannot be selected individually and therefore no actions can be triggered from a data point.

Guidelines

Number of Data Points

There is no technical limitation regarding the number of data points, but be aware that the user experience can be very degraded when there are too many data points. For example, labels in the horizontal axis will be displayed at 450. In the bubble chart, too many bubbles might lead to unreadable information.

Chart Title

The chart title is always visible for each chart type. It is used to describe the axis titles within the chart. The chart title is constructed by the measures and dimensions used in the chart. For example, Revenue by Quarter conveys that the y-axis represents the revenue and x-axis represents the quarters. The title will get truncated at the end of the line.

Time Axis

The time axis is more responsive and shows information in much better manner compared to the category axis. Currently the time axis is supported for the line, column, stacked column, bubble and combination charts. You could use these chart types either with the category or with the time axis. We recommend using the time axis when the category items represent a time series.

The time axis has three main advantages:

  • It allows you to display dates and times in a responsive manner.
  • All the complexity involved with formatting the axis labels is automatically taken care of.
  • The physical spacing between the data points accurately represents the time scale, as opposed to being equidistant.

Axis Title

The axis titles are always hidden, except in the bubble and scatter plot charts. For those charts, use the chart title of the analytical card to convey this information. For example, Revenue by Quarter conveys that the y-axis represents the revenue and x-axis represents the quarters.

Axis Scaling

There are 3 options regarding the axis scaling for the line, bubble and scatter charts:

  • Default: The minimum and maximum are calculated from the data set. 0 is always visible.
  • Adjust scale: The minimum and maximum are calculated from the data set. 0 is not always visible.
  • Min-max: Manually set by the app developer.

Axis Labels

Try to avoid displaying labels at 450. Use abbreviations for dates, such as Jan or Feb for months, or Q1 or Q2 for quarters.

Semantic Patterns

The analytical card supports semantic patterns, such as dashes, dots, or hatches, in order to distinguish:

  • Actual values: What values are (solid pattern).
  • Projected values: What values might be (dashed line, hatched areas).

Currently, semantic patterns are supported for the following chart types: line chart, column chart, and vertical bullet chart.

Semantic Colors Based on Values

Use semantic coloring based on values when you want to show data points that are positive, neutral, or negative. Based on the defined threshold values, the color of each data point could be red, green, or orange. For more information on color use, see colors.

Legend

Colors are automatically assigned and cannot be customized.

View Switch

The view switch functionality provides the user with different views of the data in one card. It can be used for filtering, sorting, or grouping (such as by supplier or material group). The view switch is optional.

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

Implementation

  • No links.

Form

Information
With version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Display-only: the data is presented only as label-value field pairs without editable fields.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form control in display only
Form control in display only
Mixed form with editable and non-editable fields
Mixed form with editable and non-editable fields
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Information
Please consider, that a read-only state of an input element behaves differently (no border and background of the field) within the sap.ui.comp.smartform.SmartForm.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form with a label-field-ratio 3:5:4
Form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.

Please change the default 2:10:0 according to your app’s needs (see the recommended layouts in the Layout section).

Form in size M
Form in size M

Size L

The form, simple form, and smart form in size L use a two-column layout within the responsive grid layout by default. That means that the form groups are placed next to each other to have all the information on one screen and to avoid scrolling. In these columns, the labels are positioned in the same row as the corresponding input field or value. So the form groups adopt the Z layout (reading direction in rows, not in columns).

The label-field ratio is 4:8:0 by default:

  • 4 grid columns of the responsive grid layout are used by the labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size L
Form in size L

Size XL

Like the form, the simple form, and the smart form in size L, the size XL uses also a two-column layout within the responsive grid layout by default. To have all the information on one screen and avoid scrolling, the form groups are placed next to each other.  In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

The label-field ratio for size XL is 4:8:0 (technically the value is set to -1 and inherits the value of size L, see also the development hint below) by default:

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. Just use the corresponding property and the asterisk will be inserted automatically.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Never repeat the label in the placeholder text. Only offer a placeholder if it provides the user with additional information.

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

Implementation

Label

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

Label
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, such as in display-only forms; do not use the label to display the data.

Types

There are two types of labels:

  • Required
  • Not required

To indicate that a field is mandatory, set the property:required. An asterisk will be automatically set in front of the label.

Required label in an editable form (horizontal layout)
Required label in an editable form (horizontal layout)
Label in a display-only form (horizontal layout)
Label in a display-only form (horizontal layout)
Non-required label in an editable form (horizontal layout)
Non-required label in an editable form (horizontal layout)
Label in a display-only form (horizontal layout)
Label in a display-only form (horizontal layout)
Non required label in an editable form (vertical layout)
Non required label in an editable form (vertical layout)
Label in a display-only form (vertical layout)
Label in a display-only form (vertical layout)

Guidelines

  • Always use a label for form controls.
  • Use title case for labels.
  • Do not use a placeholder (input prompt) as a replacement for the label.
  • Do not use bold labels.

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 (username and password), the labels do not have to be used.
  • When the form is extremely small and has fewer than three input fields, such as in messaging and 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

Implementation

  • Label (SAPUI5 samples)
  • Label (SAPUI5 API reference)

Avatar

The avatar is a control that has various display options for representing images, icons, and initials.

Usage

Use the avatar if:

  • You want to display an image in a circular shape.
  • You want to use predefined sizes.
  • You want to display icons or initials.
  • You want to have placeholder images in case no image is provided.

Do not use the avatar if:

  • You would like to integrate an image into your app for any other use case. Instead, use the image control.
  • You want to display pictures in a carousel. Instead, use the carousel control.

Responsiveness

The avatar control has predefined sizes which are the same for both form factors – compact and cozy.

Types

Shapes

The avatar control can be set to a circular or square shape.

Avatar with both circular and squared shape
Avatar with both circular and squared shape

Content

The control can show images, icons, or initials.

Avatar showing an image, initials and an icon
Avatar showing an image, initials and an icon

Initials

The control can only display up to 2 Latin letters. If more or non-Latin letters are present, a placeholder will be shown.

Avatar with initials
Avatar with initials

Placeholder

If there is no image, icon, or initials provided, the avatar will show a default placeholder. There are two types of placeholders that can be shown. If the avatar is circular, a person icon will be shown. If the avatar is square, a product icon will be shown.

Avatar default placeholders for person and product
Avatar default placeholders for person and product

Custom Size

You can also set a custom size for the avatar.

Avatar with custom size
Avatar with custom size

Predefined Sizes

The avatar control has five predefined sizes:

  • XL – 7 rem
  • L – 5 rem
  • M – 4 rem
  • S – 3 rem
  • XS – 2 rem

The predefined sizes are the same for both form factors – compact and cozy.

Predefined sizes - XL, L, M, S, XS
Predefined sizes - XL, L, M, S, XS
Predefined sizes - XL, L, M, S, XS
Predefined sizes - XL, L, M, S, XS

Fitting Images

With the imageFitType property, the avatar can fit images in two ways: Cover and Contain. The default value of the property is Cover.

Avatar with Cover and Contain property
Avatar with Cover and Contain property

Guidelines

  • Use the circular shape to display images of a person or contact.
  • Use the square shape to display images of a product, logo, and so on.
  • If you need to define a size different from the predefined one, make sure that the font size is consistent with the size of the control itself.
  • If you use initials or icons and want to display a custom size for the avatar that is between two predefined sizes, use the predefined font size for the smaller one. For example, if your avatar is 5.5 rem, between sizes L and XL, then you should use the font size for size L: 2 rem.
  • For accessibility reasons, provide each image in the avatar with an alternative text in case the image is not available or cannot be displayed.
  • High-resolution images that are unnecessarily large in file size can drastically slow down page speed. Optimize your images in this case.

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

Implementation

Busy Dialog

The busy dialog informs the user about an ongoing operation. During the operation, the entire screen is blocked.

Usage

Use the busy dialog if:

  • The user should not be able to start any other activity during an operation, and the screen needs to be blocked while the operation is ongoing.
  • The operation lasts more than one second.
  • You want to indicate loading in a page-to-page navigation.

Do not use the busy dialog if:

  • The operation lasts less than one second.
  • The screen is not supposed to be blocked. In this case, use the busy indicator or busy state of the control instead.

Responsiveness

The busy dialog is fully responsive and can be shown in compact and cozy mode.

Busy dialog - Compact mode
Busy dialog - Compact mode
Busy dialog - Cozy mode
Busy dialog - Cozy mode
Busy dialog on smartphone
Busy dialog on smartphone
Developer Hint
To switch to compact mode for a dialog, you need to use:

jQuery.sap.syncStyleClass(“sapUiSizeCompact”, this.getView(), this._oDialog);

For more information, see the SAPUI5 Demo Kit.

Components

The busy dialog can consist of several components and is configurable. The following properties can be set:

  • Title: By default, it has no title. Therefore, do not use this property.
  • Text: Additional text can be added above the busy animation.
  • Cancel:(Property:showCancelButton) A Cancel button is displayed. There is no Cancel button by default. The label is also configurable via Property.cancelButtonText.
  • Icon: A custom animation icon can be set via Property:customIcon.

If no title, text, or Cancel button is set, the busy dialog displays only the busy icon (busy dialog, lightweight version).

Busy dialog without title
Busy dialog without title
Busy dialog without title and Cancel
Busy dialog without title and Cancel
Busy dialog - Lightweight version
Busy dialog - Lightweight version

Guidelines

Lightweight Version (No Title, Text, or Cancel Button)

  • Use the lightweight version for page navigation (see live example).

  • If you do not show a title or text, use the invisible text control (sap.ui.core.InvisibleText) to provide the reason for the busy state to users with assistive technologies.

Developer Hint

The additional text should be associated to the busy dialog using ariaLabelledBy association.

Busy Dialog with Text

  • Do not use the title of the busy dialog.
  • If a busy dialog is triggered directly by the user, provide a precise text describing the operation. The text can be as short as one verb:
    • Loading…
    • Refreshing…
    • Sending…
  • If the busy dialog is not directly initiated by the end user, use at least one sentence to describe the operation. Start either the first or the last sentence with Please wait. For example: The system is busy searching data. Please wait until data is loaded.

  • Recommendation: Do not use the invisible text control when you show text in the busy dialog.

Busy Dialog with Text and Cancel Button

  • Offer Cancel if you expect the process to run more than 10 seconds. In addition, always display text that precisely describes the ongoing operation.
  • Do not change the mouse cursor to indicate the ongoing operation.
  • Recommendation: Do not use the invisible text control when you show text in the busy dialog.

Timing and Duration

We recommend displaying the busy dialog one second after the process has been triggered and for a minimum time of 500 ms to avoid flickering. For processes that last less then one second, a busy dialog is not displayed at all.

Example: A process takes 1.3 s in total. After one second, the busy dialog is displayed. The process finishes in 1.3 seconds. To avoid flickering, you should display the busy dialog for at least 500 ms, so you will need to add 200 ms to avoid flickering.

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

Implementation

Image

Images are not only for decoration. They can be a powerful way to capture the user’s attention and communicate your message. You can use the image control to integrate images into your apps. Images are visual representations of objects or functions.

Responsiveness

The size of the image is simply adjusted to the amount of space available.

Size S (Smartphones)

Object page (size S)
Object page (size S)

Size M (Tablets)

Object page (size M)
Object page (size M)

Size L (Desktops)

Object view (size L)
Object view (size L)

Layout

Images can be used in various locations in the app, such as in a list cell or object header, and also in the content area. App developers determine the most appropriate area. See the examples below.

Images placed in a table
Images placed in a table
Image placed in the object header
Image placed in the object header
Image placed in a carousel
Image placed in a carousel
Image placed in a dialog
Image placed in a dialog

Behavior and Interaction

Clicking an Image (Optional)

Various options are available in terms of size setting, and the images can also be combined with actions. The most common behavior is clicking the image to enlarge it.

  • Dialog

Properties

  • The original image size can be modified.
  • An image can be decorative only.
  • An image can be connected to an image map.
  • You can trigger an action for navigation.
  • Connection to an on-screen user assistance is supported.

Guidelines

  • For accessibility reasons, provide each image with an alternative text in case the image is not available or cannot be displayed.
  • Do not use placeholder images if you do not plan to replace them with real images.
  • Do not use icons as images. There is a separate icon font for such cases, which consists of more than 500 scalable pictograms in SAP’s illustrative style.
  • It is extremely important that you choose the right file format when saving your images. Three image formats are used consistently in browsers – PNG, JPG, and GIF.
  • When choosing the format for your image, you should always be conscious of the image quality and file size.
  • High-resolution images that are unnecessarily large in file size can drastically slow down page speed. Optimize your images in this case.
Good quality
Good quality
Poor quality
Poor quality

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

Implementation

  • Image (SAPUI5 samples)
  • Image (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
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
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 or tapping 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 or tapping a new position. The tokens between these two cursor positions are then selected.

To replace a token, the user selects it and enters new characters.

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 or tapping 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
Regular
On hover
On hover
Selected
Selected
Read only
Read only
Hover selected
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

Implementation

Search

A search is a means of accessing information quickly. If an amount of data is too large for users to find something just by scanning through it, you should consider providing a search function.

Search field
Search field

Usage

Use a search field (sap.m.SearchField) if you want to enable users to enter text to search for information. The search field is also the control of choice for filtering down a given amount of information.

Responsiveness

On tablets (size M) and smartphones (size S), the master list’s search field is not initially visible. It only appears when the user pulls down the list. Its position is not fixed, so it scrolls away. On desktops (size L), the master list’s search field is visible from the start. Its position is fixed and it does not scroll away.

Master list with search field
Master list with search field
Searching in the master list - Search field on focus
Searching in the master list - Search field on focus
Searching in the master list
Searching in the master list

Types

SAP Fiori comes with two different search types.

  1. The manual searchis triggered explicitly after the user enters text in the search field and clicks or taps the Search button or presses the Enter key.
  2. The live search(also known as “incremental search” or “search-as-you-type”) is triggered by each character that the user enters or deletes.

Queries that are entered are used to search the backend data for term matches (not case-sensitive). While a live search uses a “contains” approach, a manual search uses a “starts with” approach. “Contains” means that the result needs to match the query only partly to be a valid result. “Starts with” means that full terms of the result need to start with the entered query to be visualized.

Layout

The search input field (or search box) consists of two parts:

  1. The text input, which is left-aligned. Initially, the field shows a placeholder (Search). As soon as the user enters a character, this prompt text disappears. It appears again if the user deletes the entry.
  2. If a manual search is to be implemented, a search button with a magnifier icon is placed on the right side of this input control. The user clicks or taps this button to trigger the search. In live searches, the magnifier icon is also placed here, but it functions more like an additional indicator to signify that this is a search input field. It also functions as an explicit search button if the user wants to search again for a query that has already been entered.

All item attributes defined by the app development team are searched. When the results are displayed, the items found do not necessarily have to show the attribute through which the item was found. The results are displayed in the same list that contained the original item set. Initial grouping and the order of the list are not affected by the search.

When the split screen is used, the search field appears at the top of the master list. In full screen mode, the search field is placed at the top of the page.

Behavior and Interaction

Entering a Search Term

Search terms can be entered easily into the input field. The search box then displays all full-text search terms. There is no line break and no truncation if the query is longer than the input field. Results might also be displayed that do not match the query in their title or subtitle. This might be because details can also be searched for. The user can see the matching terms in the specific details section.

Deleting a Search Term

The user can click or tap the ex ( ) button to remove the text from the field. In the case of the live search, this also resets the search. In a manual search, deleting the search term and then triggering the search resets the search results.

Refreshing

If the Refresh button is available, the user can update the list without triggering a new search. This is usually needed when backend data changes quickly and often.

If the currently selected item is no longer available after the list has been refreshed, the next item in the line is selected. If no next item is available, the first item in the line should be selected next.

Search field with refresh
Search field with refresh

On touch devices, the Refresh icon is not visible in the search field. In this case, Pull Down to Refresh is used instead. The Pull Down to Refresh arrow icon is animated and spins to signal that the user should release it.

Pull to Refresh

  • On mobile - Pull to refresh
  • On mobile - Release to refresh
  • Loading..
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.

Properties

The following methods are important.

For the live search:

  • attachLiveChange(oData?, fnFunction, oListener?) Attach event handler fnFunction to the ‘liveChange’ event of this sap.m.SearchField.
  • detachLiveChange(fnFunction, oListener) Detach event handler fnFunction from the ‘liveChange’ event of this sap.m.SearchField.
  • fireLiveChange(mArguments?) Fire event liveChange to attached listeners.

For the manual search:

  • attachSearch(oData?, fnFunction, oListener?) Attach event handler fnFunction to the ‘search’ event of this sap.m.SearchField.
  • detachSearch(fnFunction, oListener) Detach event handler fnFunction from the ‘search’ event of this sap.m.SearchField.
  • fireSearch(mArguments?) Fire event search to attached listeners.

If a Refresh button is needed:

To show the Search button:

To ensure the focus is set to input:

Guidelines

  • Implement the live search whenever possible.
  • Use a manual search only if the amount of data is too large and if your app would otherwise run into performance issues.
  • Show an appropriate prompt text:Search if queries are sent to all connected services, or Search In: if the search is limited to a certain source or providing service.

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

Implementation

Multi-Input Field

A multi-input field allows the user to enter multiple values, which are displayed as tokens. These can be displayed in single and multiline mode. To help the user enter a valid value, you can enable the autocomplete 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.

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.

Responsiveness

In the examples below, the autocomplete feature is shown in different sizes for single and multiline modes.

Single Line Mode (Default)

Size S (Smartphones)

  • Cozy mode.
  • When the user taps the multi-input field, a new full-screen dialog opens in which the autocomplete 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.
Autocomplete feature on a smartphone (size S)
Autocomplete feature on a smartphone (size S)
Users can review tokens by swiping left and right on touch devices
Users can review tokens by swiping left and right on touch devices

Size M (Tablets)

  • Cozy mode.
  • The user can review tokens by swiping them to the left or right.
  • The autocomplete suggestions appear below or above the multi-input field.
Autocomplete on a tablet (size M)
Autocomplete on a tablet (size M)

Size L (Desktops)

  • Compact mode.
  • The user can review tokens by pressing the right or left arrows on the keyboard.
  • The autocomplete suggestions appear below or above the multi-input field.
Autocomplete on a desktop (size L)
Autocomplete on a desktop (size L)

Multiline Mode

Size S (Smartphones)

  • Cozy mode.
  • When the user taps the multi-input field, a new full-screen dialog opens in which the suggested items can be selected. When the user makes a selection within that dialog, the token is displayed in the input field. When the user enters a new search term, the display area of the token is replaced by the autocomplete suggestions.
Smartphone multiline mode – Closed
Smartphone multiline mode – Closed
Smartphone multiline mode – Open
Smartphone multiline mode – Open
Autocomplete on smartphone - Multiline mode
Autocomplete on smartphone - Multiline mode

Size M (Tablets)

  • Cozy mode.
  • When the user taps or focuses on the multi-input field, the single-line field expands to a multiline field. All tokens are displayed.
Tablet multiline mode – No token selcted
Tablet multiline mode – No token selcted
Tablet multiline mode active – Expanded
Tablet multiline mode active – Expanded
Tablet multiline mode – Suggest
Tablet multiline mode – Suggest

Size L (Desktops)

  • Compact mode.
  • When the user focuses on the multi-input field, it expands to a multiline field.
  • The autocomplete suggestions open below the multi-input field.
Desktop multiline mode – Not focused
Desktop multiline mode – Not focused
Desktop multiline mode active – Expanded
Desktop multiline mode active – Expanded
Desktop multiline mode – Suggest
Desktop multiline mode – Suggest

Types

The input types of the multi-input are identical to those of the input field. For more information, see input field.

Behavior and Interaction

Single Line Mode

Adding a Token

The user can add a token via autocomplete suggestions or value help. When an item is selected from the autocomplete box, the corresponding token is created. The input 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 tokens
Adding a second token
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

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
Left/right keyboard cursor
Swiping left and right on a touch device
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
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:

Value help with select dialog
Value help with select dialog
Value help with value help dialog
Value help with value help dialog

Multiline Mode

Single line mode is active by default, so to activate multiline mode, you need to enable it (property: enableMultiLineMode).

Adding a Token

The user can add a token via autocomplete suggestions or value help. The token is created by selecting an item from the autocomplete box. The input is ready for the next entry. Tokens are placed next to each other. If there is not enough space on one line, the control expands.

Adding a token
Adding a token

Reviewing Tokens

When the multi-input field is not focused, it is shown in collapsed mode. The token that was entered last is displayed. If there is more than one token, the number of hidden tokens is shown next to the last token.

When tokens are entered into the multi-input field, the control expands to show all tokens. On screen size S, a new dialog is opened to review the tokens.

Reviewing tokens
Reviewing tokens

Copying and Pasting Data from a Spreadsheet or Text File

The multi-input control 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 a whole column in the spreadsheet and copies it. When items are entered into the multi-input field, the user just pastes them from the clipboard and each item is represented as a token.

Guidelines

  • Use the multiline mode instead of the single line mode (default). This provides greater flexibility for displaying multiple tokens.
  • 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.

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

Implementation

Chart Types

The following chart types are available in vizFrame:

Bar Chart

  • Simple
  • With dual axis

Bubble Chart

  • With horizontal value axis
  • With horizontal time axis

Bullet Chart

  • Vertical
  • Vertical with Time Axis
  • Horizontal

For guidelines, see bullet chart.

Combined Column and Line Chart

  • With categorical axis
  • With categorical axis and dual axis
  • With time axis
  • With time axis and dual axis

Combined Stacked Column and Line Chart

  • With categorical axis
  • With dual axis

Column Chart

  • With categorical axis
  • With time axis
  • With dual axis

For guidelines, see column chart.

Donut Chart

  • Donut chart
  • Pie chart

Heatmap

  • Heatmap chart

Line Chart

  • With categorical axis
  • With time axis
  • With dual axis

Scatter Chart

  • With horizontal value axis
  • With horizontal time axis

Stacked Bar Chart

  • Simple
  • 100%
  • With dual axis

Stacked Column Chart

  • With categorical axis
  • With dual axis
  • With time axis
  • 100% with categorical axis
  • 100% with dual axis
  • 100% with time axis

Waterfall Chart

  • Horizontal
  • Vertical with categorical axis
  • Vertical with time axis
  • Vertical with time axis and multiple series (periodic)

For guidelines, see waterfall 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

Implementation

No links.

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
Calendar date interval

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

Special day markup
Special day markup

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

Alternative start date
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
Sizes M and L

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

Size S
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 naturally 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. 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
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 or taps 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 or tapping 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 month

Navigation by Year

The user triggers year navigation mode by clicking or tapping 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
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 or taps 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
Selection – Single day

Multiple days

The user clicks or taps 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
Selection – Multiple days

Day range

The user clicks or taps 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
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

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 smartphone
Date picker on a desktop
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 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.

Date picker with selected date and the current date
Date picker with selected date and the current date
Clickable areas of the date picker
Clickable areas of the date picker

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.

Clickable areas
Clickable areas

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

Navigating to the next month
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
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
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
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
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

Implementation

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 S)
Date range selection (size L)
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
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.

Clickable areas: The dates November 9–17 are selected, and November 27 is shown as the current day
Clickable areas: The dates November 9–17 are selected, and November 27 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.

Date range selection
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.

Clicking the month shows an overview of all months.

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.

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.

Selecting an End Date

When the user selects an end date, the calendar closes.

Selecting a Range

After the user selects a range, the calendar closes and the range appears in the date input field.

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 picker with default placeholder
Date range picker 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
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
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
Long display format
Medium display format
Medium display format
Short 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

Implementation

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 (for a tablet or desktop, for example)
The date/time picker opens in a popover for sizes M and L (for a tablet or desktop, for example)
The date/time picker opens in a popover for mobile size (for a smartphone, for example)
The date/time picker opens in a popover for mobile size (for a smartphone, for example)

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.

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 – Open
Date/time picker – Closed
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. Clicking a date in the calendar automatically leads 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.

Date/time picker opens in a popup for size S.
Date/time picker opens in a popup for size S.
Date/time picker opens in a popover for mobile size (for a smartphone, for example)
Date/time picker opens in a popover for mobile size (for a smartphone, for example)

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
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.

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

Implementation

Snapping Header

The snapping header is the uppermost element of the object page layout. It summarizes selected data and actions in a visually prioritized position to let the user quickly grasp the most relevant information.

Currently, the snapping header is only available for the object page floorplan.

Usage

Use the snapping header if:

  • You are creating an object page manually based on the object page floorplan.

Do not use the snapping header if:

  • You are using any other floorplan.

Responsiveness

The snapping header is designed to provide maximum flexibility. It adapts automatically to small, medium, and large screen sizes.

The header title and subtitle are never truncated. If necessary, the text wraps to the next line.

The toolbar follows the standard toolbar overflow guidelines by adding the available buttons to the overflow menu from right to left.

Object Header Content Priority

Each facet in the header content area has a priority assigned to it. Content prioritization aims to support responsive behavior. Priorities allow less important content to be omitted from rendering, depending on the screen space available. The user can always access omitted content on request.

Three priority types are available: high, medium, and low. According to the screen size, the facets are distributed as follows:

  • Size L/XL: The facets with high, medium, and low priority are displayed.
  • Size M: The facets with high and medium priority are displayed.
  • Size S: Only the facets with high priority are shown.
Snapping header – Responsiveness – Size S
Snapping header – Responsiveness – Size S
Snapping header – Responsiveness – Size M
Snapping header – Responsiveness – Size M
Snapping header – Responsiveness – Size L/XL
Snapping header – Responsiveness – Size L/XL
Object header content priority for sizes S
Object header content priority for sizes S
Object header content priority for sizes M
Object header content priority for sizes M
Object header content priority for sizes L
Object header content priority for sizes L

Components

The snapping header comprises two main control elements:

  • Mandatory: Title bar (sap.uxap.ObjectPageHeader)
  • Optional: Header content (sap.uxap.ObjectPageHeaderContent)

There are different states for the snapping header. You can find further information under Behavior and Interaction in this article.

Title Bar

The title bar comprises the following elements:

  • Header title (mandatory): The title is always visible.
  • Header subtitle (optional)
  • Title bar image (optional): The image has a shape parameter (square or with a round mask) and a placeholder parameter. A placeholder is displayed if no specific image is available.
  • Toolbar: The toolbar contains the global actions for the floorplan. The actions should be represented only with buttons, text, or an icon. They can be transparent, regular, highlighted, or semantic. All buttons go from right to left into the overflow. Buttons should be arranged according to the current use case and always in a consistent visual order (see guidelines section below for example). If there are no global actions, the toolbar is not shown. Note that the object page uses the sap.m.Toolbar control instead of sap.m.OverflowToolbar.
  • Child page visualization: Each object page can have drilldown navigation. The child object page can only be reached through the parent object page. A narrow vertical stripe at the left side of the snapping header helps to differentiate the child object page from the parent object page.

The title bar can also contain the following optional indicators:

  • Favorite (property: markFavorite)
  • Flagged (property: markFlagged)
  • Locked (propertly: markLocked)
  • Selector (property: showTitleSelector)
  • Unsaved Changes (property: markChanges)

The title bar control also supports breadcrumb navigation. For more information scroll to section line item navigation.

Snapping header – Structure
Snapping header – Structure

Header Content

The header content is optional and located below the title bar.

You can use the header content (sap.uxap.ObjectPageHeaderContent) to display app-specific contextual information. You build the content using smaller content containers, called facets. Each facet contains a distinct information set, as described below. If there aren’t any facets, the header content is always hidden.

The facets are arranged in line with a left float. Each facet adapts its size to the content and makes optimal use of the space without truncating the texts. If the facets do not all fit on one line, those on the right wrap to the line below.

If the snapping header collapses, the header content is hidden. If the header content is empty, you can also hide it.

Header container – Floating content
Header container – Floating content

Header Facets

There are several types of header facets, depending on the data that they display. The facets need to be handmade for stand-alone object pages.

Form Facet (Data Set)

The form facet can be used to display datasets in the snapping header. It consists of a headline and up to five label-text pairs.

Additional information:

  • The headline is optional.
  • It contains at least one but maximum five label-text pairs.
  • The labels can be invisible, but need to have a text for accessibility reasons.
  • The labels can be icons, but need to have a text for accessibility reasons.
  • Each text of a label-text pair can have a press event.

Examples for the usage of form facets include document information such as creator and creation time, an address or contact information, and general information.

Header Facet - Form Facets
Header Facet - Form Facets

Plain Text Facet

The plain text facet can be used to display a continuous text in the snapping header. It consists of a headline and a continuous text.

Additional information:

  • The width of the facet does not depend on its content, but can be set. The default width of the facet is 300px.
  • The headline is optional.
  • If the headline is broader than the facet width, the headline will wrap.
  • Press events are only available inline in the continuous text. These can be links that navigate to another page or open a quickview. There can be more than one link in the continuous text with different actions.
Header Facet - Plain text facet with default width
Header Facet - Plain text facet with default width
Header Facet - Plain text facet with custom width
Header Facet - Plain text facet with custom width

Image Facet

The image facet can hold exactly one image. The snapping header can only hold one or no image facet.

Additional information:

  • The image can be either square or round.
  • The image can also hold an icon.
  • The image can also hold initials consisting of two letters.
  • The image can have a press event. The default press event is the enlargement of the image.#
  • When the header collapses, the image facet will move to the right of the title and become smaller.

Recommended usage of the different properties:

  • Images of people, especially portraits, should be round. If there is no image for a person, initials (first letters from first and last name) should be used instead.
  • All other images should be square. If there is no image for an object, an appropriate icon should be shown.

In all cases, it should be clear how the images will be managed and uploaded. This can either be via the edit mode of the object page or, especially where there are lots of images, via an external tool.

Header facet – Image facet specification
Header facet – Image facet specification

Key Value Facet

The key value facet holds a label in a smaller font size and a text or number in a bigger font size. It can be used to highlight important data or KPIs of the object.

If the key value facet is used with a text such as a status, it can also have an icon on the right side next to the text. This icon has to belong to the text and should only visually support but not expand it.

Header Facet – Key value facets with KPIs and a status
Header Facet – Key value facets with KPIs and a status

Micro Chart Facet

The micro chart facet consists of a headline, a subtitle, a micro chart and a footer.

The headline and the micro chart are mandatory, while the subtitle and the footer are optional. To display the unit used in the micro chart, the footer should be used.

The following micro charts can be used in the micro chart facet:

  • Bullet Chart
  • Column Chart
  • Trend Chart
  • Comparison Chart
  • Delta Chart
  • Harvey Ball Chart
  • Radial Chart

The micro chart facet can have a click or tap event on the chart itself. This could, for example, lead to a page with a bigger chart or open a quickview.

For more information see micro charts.

Header facet – Micro chart facets
Header facet – Micro chart facets

Progress Indicator Facet

The progress indicator facet consists of a mandatory headline and a progress indicator (sap.m.progressIndicator). It can also contain two optional supplementary texts: a subtitle and a footer.

Header facet - Progress indicator facet
Header facet - Progress indicator facet

 Rating Indicator Facet

The rating indicator facet consists of a headline, a rating indicator and one or two supplementary texts, which are dependent on the use case as described below.

The rating indicator can be modified as described in the rating indicator article.

Guidelines for using the rating indicator in the header facet:

  • Use 5 symbols as default.
  • Use the “favorite” icon as symbols.
  • Use the option to display half stars for decimal values.

 

The rating indicator facet can be used for two different use cases as described below:

  1. Aggregated RatingWhen displaying an aggregated rating, which could be for example the average of several user reviews for a product, the facet can contain a mandatory header, an optional subtitle, the rating indicator, and a footer.The subtitle should display the amount of data on which the aggregation is based. For example, in the case of an average rating, the subtitle would show the number of ratings.The footer should show the exact value of the aggregation in the format “2.2 out of 5”, where “2.2” indicates the exact value of the aggregation, and “out of 5” indicates the maximum value of the rating.
  2. Single Value Rating When displaying the rating as a single value, the facet can have a mandatory header, an optional subtitle, and the rating indicator. Here the subtitle can be used as supplementary text, and a footer should not be used.
Header facet - Rating indicator facet with aggregated rating
Header facet - Rating indicator facet with aggregated rating
Header facet - Rating indicator facet with singe value rating
Header facet - Rating indicator facet with singe value rating

Behavior and Interaction

The snapping header has different types of behavior that can be combined:

  • Snapping
  • Title bar only
  • Header content always shown
  • Child page visualization
  • Line item navigation
  • Edit

By default, the snapping is enabled and title bar and header content are shown (expanded).

Snapping

The snapping header is always expanded for all display sizes when the user opens the object page .

When the user scrolls down the page, the header content snaps closed (collapses), leaving only the title bar. This allows the user to see more of the object page content.

You can specify which information is shown in the title bar in the expanded and collapsed states. In the following example, the snapping header has been configured to show only the image in the title bar when the header content area is collapsed.

Snapping header – Expanded
Snapping header – Expanded
Snapping header – Collapsed
Snapping header – Collapsed

Title Bar Only

If there is no need for the header content, the title bar only mode can be used. This means that there is no snapping behavior, because the title bar is always shown.

Header Content Always Shown

The snapping header can remain expanded while the user scrolls down the page if the property alwaysShowContentHeader is set to true for the object page layout (sap.uxap.ObjectPageLayout). This behavior is only available for desktops.

Child Page Visualization

Each object page can have drilldown navigation. The child object page can only be reached through the parent object page. A narrow vertical stripe on the left side of the snapping header helps to differentiate the child object page from the parent object page. To navigate between the child object pages of one parent object page, arrows are displayed within the header bar of the page. Breadcrumbs allow the user to easily navigate back to the object page. To enable the child page visualization, use the property isChildPage of the sap.uxap.ObjectPageLayout.

Child page visualization – Vertical stripe
Child page visualization – Vertical stripe

Line Item Navigation

The snapping header for the object page can contain a breadcrumb showing the navigation path for the current item. This feature was developed specifically for line item navigation within the object page.

The breadcrumb is located above the title in the title bar. The interaction is typical of a breadcrumb navigation pattern: all links in the breadcrumb chain point to a URL and are triggered by a press event.

If there is not enough space to show the full breadcrumb, it defaults to a dropdown control. In this case, the breadcrumb shows only the immediate parent of the current item. The   symbol indicates that further information is available in a dropdown list.

The dropdown list reveals all the links in the breadcrumb chain. The user reads the breadcrumb from bottom to top: The root object is at the bottom of the list, the immediate parent is at the top, and the current item is selected.

Breadcrumb – Truncation handling
Breadcrumb – Truncation handling

Edit

There are two different ways to edit the header information:

  • Global edit
  • Partial edit

Please note: The majority of object pages do not have editable header content. Therefore, the object header should not be editable by default.

Global edit

A button in the header toolbar triggers the edit mode. For more information on global editing, see object page.

The visible facets can differ in create, edit and display mode. If there aren’t any facets in one mode, the header content is not displayed. Choose which information supports the user best in his or her current task. The thought behind this possibility assumes that a number of header facets  are assigned to one given application. You can define which facets are shown in which mode.

Once the edit mode is activated, the header content is moved to a section in the content area of the object page. This section is assigned the anchor label Header. This is the first section in the document. All other sections are displayed in the order in which they are displayed in display mode. If editable, the object page title, subtitle, and image appear in the header content section. They also remain visible in the header title bar. If changed, they are shown only in preview mode. The user will have to save the document to actually enable the changes.

Exemplary scenarios when switching from display to edit mode:

  • All header elements are editable: All of the header elements are displayed as editable forms in the Header section. The header content hides as no facets are displayed.
Global edit – All header facets editable
Global edit – All header facets editable
  • Only some of the header elements are editable. All of the header elements are displayed in the Header section, but the content that is not editable is displayed as read-only to keep the layout consistent.
Global edit – Some header facets editable
Global edit – Some header facets editable
  • Independent header facets are present in edit mode: All of the header elements are displayed as editable forms in the Header section. A new facet that is related to the data that the user is editing is displayed in the object page header content area. This header facet is not shown in display mode.
Global edit – Edit with header container and independent header facets
Global edit – Edit with header container and independent header facets

Partial Edit

Partial edit is used when the object page consists of large data sets and the user wants to be able to edit only the object header. Edit mode is triggered by a button that is located on the bottom right of the snapping header.

When there are only a few elements to be edited, the Edit Header button opens a dialog. When there are more editable elements, the button triggers a subpage. This subpage contains all editable data from the header without the toolbar, the navigation, or the breadcrumbs.

Partial edit – Editing in a dialog
Partial edit – Editing in a dialog

Style

The snapping header is available with two themes (property headerDesign):

  • Light flavor(default)
  • Dark flavor (restricted)

The dark flavor does not yet support all controls in the header content area. The first version of the snapping header is not themeable and uses hard-coded colors.  As a result, the dark header theme might cause contrast problems with some controls. For example, you might need to set lighter links (Less parameter: @sapUiLink, 40).

Snapping header – Light flavor
Snapping header – Light flavor
Snapping header – Dark flavor
Snapping header – Dark flavor

Guidelines

Breadcrumbs
Use breadcrumb navigation only on the object page, and only where there is a hierarchical drilldown within the object (line item navigation). For other types of navigation, see the SAP Fiori navigation patterns.

Header toolbar
Do not use input fields, selects, checkboxes, search fields, or similar controls in the header toolbar. Use buttons only.

Header content area
Place only meaningful information in the header content containers. The content should help the user in the object context, or provide useful reference information.

Keep the header as clean and uncluttered as possible to allow users to take in the content at a glance. If there is too much information in the header, consider placing an overview section in the content area of the object page floorplan.

Themes

Until theme parameters are available for the snapping header, we recommend using the light flavor. This will avoid any contrast issues that might arise with the dark theme in the current implementation.

Images
When images are used in the object page header, you should consider the following needs:

  • How will the user manage the images?
  • How will the system block people without permission for image editing?
  • How will these images be reflected in other floorplans if they are part of the object?
  • If there are a large number of items, how would a company be able to manage images without having to navigate from page to page?
  • Will the company be able to manage the images?
Developer Hint
How to achieve a small header:

  • The header container is always optional. If there is no important data to be displayed, you can omit it.  In this case, only the header title bar will be shown.
  • Omit the image if it is not necessary. It is generally the tallest element in a header container.
  • Use a light theme to reduce the emphasis in the header if there is not much information on it.
  • You can always place the information from the header into a general information section.

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

Implementation

Timeline

The timeline control shows entries (such as objects, events, or posts) in chronological order.

A common use case is to provide information about changes to an object, or events related to an object. These entries can be generated by the system (for example, value XY changed from A to B), or added manually. The latest entry is always on top.

There are two distinct variants of the timeline: basic and social. The basic timeline is read-only, while the social timeline offers a high level of interaction and collaboration, and is integrated within SAP Jam.

Developer Hint
Information stemming from SAPUI5 SDK: Starting with version 1.34, use the group feed component (sap.collaboration.components.feed.Component) and business object mode (sap.collaboration.FeedType.BusinessObjectGroups) for new integrations and existing implementations running on versions 1.32 and up. Note that the group feed component does not display any updates related to the business object from the backend system (system updates).

Usage

The timeline does not have a fixed location on the UI. Where you place it strongly depends on your use case.

For example:

  • If the timeline is closely related to the content and needs to be seen in parallel, you can use the dynamic side content floorplan.
  • If the timeline contains only secondary information, or only needs to be accessed occasionally, you can embed it in a tab.
  • If you are using the object page floorplan, you can use the horizontal layout to integrate the timeline (see Orientation in the Styles section below).

These are just some of the ways you can position the timeline on a page.

Use the basic timeline if:

  • You want to display read-only content, such as an object history.
  • You do not require social interaction (for example, replies).
  • Your customers do not use SAP Jam.
  • You only expect a long list of posts triggered by the system.

Do not use the timeline if:

  • You expect only a few entries. In this case, you should use a feed by combining the two controls “FeedInput” and “FeedListItem”.
  • You want to provide a way to upload files. Use the upload collection instead. You can still use the timeline to show automated updates about the user’s uploads.

Use the social timeline if:

  • You want users to be able to create their own posts.
  • You need social interaction, such as replies.
  • You expect a long list of posts triggered by users or the system.

Responsiveness

The timeline control is fully responsive and works well with multiple screen sizes.

Timeline – Size S
Timeline – Size S
Timeline – Size M
Timeline – Size M
Timeline – Size L
Timeline – Size L

Layout

The timeline control consists of:

  • A header (optional)
  • A chronological axis
  • Posts/entries

 

The following features can be used optionally:

  • Filter
  • Group
  • Add entries

 

Header

The title describes the content displayed along the timeline axis.

 

Axis

Along the axis, the entries are arranged chronologically. The distance does not correspond to the time between each occurrence.

You can use a vertical or horizontal axis. The timeline can be scrolled along its axis.

By default, the latest entries appear on top. Replies are sorted the other way round.

 

Post (Entry /Feed Update)

Posts can be generated by the system (for example, “Object ABC changed by Mr. X”), or entered manually. The entry includes information about who changed what, and when. Typically, posts in the timeline consist of four sections:

  1. A node
    Using icons on a node is optional. Use icons for either ALL or NONE of the posts.
  1. A header section, which can contain:
  1. An (expandable) content section, which can contain:
  • Text(s) and/or link(s)
  • Structured or unstructured information
  • Images
  1. An optional social section, which can contain some or all of the social features offered by SAP Jam (such as Reply, Like, Bookmark, or Share)

Note: If a section is not used, it should not take up any space within the bubble.

Timeline – Layout
Timeline – Layout

Examples for different visualizations:

Timeline – Layout examples
Timeline – Layout examples

Examples for different visualizations:

Posts can originate from three sources:

  • Manual post: A person actively posts to the timeline (or to another place that supplies updates to the timeline).

Example:
Julie Armstrong: Hey @John Miller. Can you give me an update?

  • Post triggered by user action: The post is triggered by something a person does (such as creating a poll in SAP Jam, adding a document to a group, or uploading an attachment).

Examples:

Julie Armstrong created a poll.
(Followed by a preview of the poll)

John Miller posted the document Sales-Revenue_Q4.xls
(Followed by a preview of the document, if available)

Donna Moore wrote a blog post
(Followed by a preview of the blog post)

Julie Armstrong added the picture our_team.jpg
(Followed by a preview of the image)

  • Post triggered by a technical source: Posts can also originate from a purely technical source (for example, if a threshold has been exceeded, or a deadline has been reached).

Examples:

Boiler BB-258/80 has exceeded its maximum temperature.

Server DS209 is running out of space.

Order #052690 is overdue.

Information
Notes vs. Posts: 

Notes are not the same as timeline posts. They must be kept separate and be visualized differently. Like attachments, users create notes in the context of a business object, typically within a Notes tab.

In the context of a business object, notes have to be seen in the same category as attachments.

The difference is even more apparent if you compare posts to complex notes created with a rich text editor. These notes are fundamentally different from timeline posts.

To show notes on the timeline, trigger a feed post with a teaser text. For example, “Julie Armstrong added a new note: Lorem ipsum…”.

Types

Two types of timeline are available:

  • The basic timeline is read-only without social content.
  • The social timeline allows social user interaction.

Basic Timeline

(Available for all apps without SAP Jam integration)

The basic timeline is read-only. There are no user posts, replies, likes, shares, social profile, or other social features. Only system-triggered posts appear on the timeline. User actions within the app (such as creating notes and attachments, or making calls) are reflected in the timeline automatically.

The image below shows a post in the basic timeline. The image on the right shows an example of a basic timeline.

Basic timeline – Post
Basic timeline – Post
Basic timeline
Basic timeline

Social Timeline

(Available for apps with SAP Jam integration)

With SAP Jam, all social features are enabled. Users can post updates, reply, like, and share. Both user-triggered and system-triggered posts appear on the timeline.

The image below shows a post in the social timeline. The image on the right-hand side shows an example of a social timeline.

Types – Social timeline – Post
Types – Social timeline – Post
Types – Social timeline
Types – Social timeline

Behavior and Interaction

Adding a Post

In the social timeline, users can add new posts by clicking the plus ( ) icon on top of the control.

Clicking the plus (  ) icon opens a popover with the focus set inside the text area so the user can immediately start typing.

Post sends the user’s text, which then appears in the timeline. However, the button stays inactive until the user has typed something to prevent empty posts.

Users can also add @mentions (references) to other users or business objects. Read further details below in the @Mention section.

Interaction – Post
Interaction – Post

Replying to a Post

Next to the Post functionality, Reply is probably the most basic and most essential social feature. It enables communication at item level, which is the main way in which it differs from the feed controls. With feed controls (FeedInput and FeedListItem), new entries are always added to the top of the list; there are no in-line replies in the feed. The timeline, however, allows users to reply directly to a specific entry. The number of replies is shown in the reply link, such as Replies (5).

The user clicks or taps the respective link to trigger a popover that shows all previous replies, as well as a text area that allows the user to post a personal reply.

Interaction – Reply
Interaction – Reply

@Mention

This feature is well known from multiple social networks. Like all social features, it is only available in the social timeline, where it allows users to add a reference to another person or a business object. A ‘mentioned’ person usually receives a notification about the respective post.

The @mention feature is available in all areas that allow the user to post something:

Due to technical restrictions, this feature cannot be used on smartphones for the time being.

Interaction – @Mention
Interaction – @Mention

Users trigger the feature by typing the @ sign, or by clicking or tapping the @ button provided in the footer. The button shows users who are not familiar with this feature how to use it.

The following step-by-step walk-through concentrates on the core functionality, and therefore omits the surrounding controls.

Interaction – @Mention (1)
Interaction – @Mention (1)

As soon as a user types the ‘@’ character, he or she is prompted to enter a person’s name or email address.

Interaction – @Mention (2)
Interaction – @Mention (2)

As the user continues to type, a suggestion list is shown.

Interaction – @Mention (3)
Interaction – @Mention (3)

This suggestion list is gradually reduced to only include items that match the user’s input. If the user clicks on the suggestion or finishes typing the name of an existing person, the @mention is created.

(Due to technical restrictions, @mentions cannot be visually highlighted to indicate a successful match currently. )

Search

Always offer a search with the timeline because it may contain a vast number of entries. A search helps users to find what they are looking for without having to scroll through all the posts and updates.

Initially, the search field is closed and only visualized with a search icon.

Clicking on the icon opens…

… the search field with the focus in the field so the user can start to type immediately.

  • Interaction - Search (1)
  • Interaction - Search (2)
  • Interaction - Search (3)

Filter (Optional)

For timelines with several entry types, it makes sense to enable filtering. You can let users filter the timeline by entry type and by other useful attributes (such as bookmarked for bookmarked items).

The filter is triggered with the respective icon in the toolbar.

Timeline interaction – Filter
Timeline interaction – Filter

Depending on the complexity of the timeline, you can offer different kinds of filter dialog:

  • Single selection
Timeline interaction – Filter with single selection
Timeline interaction – Filter with single selection
  • Multi-selection
Timeline interaction – Filter with multi selection
Timeline interaction – Filter with multi selection
Multi-faceted filter
To implement this combination of feed source and filter, use the view settings dialog (sap.m.ViewSettingsDialog).
Interaction – Filter with ViewSettingsDialog
Interaction – Filter with ViewSettingsDialog

If a filter is set, inform the user in the info bar.

Timeline interaction – Set filter
Timeline interaction – Set filter

Show More

After a certain number of timeline entries, a Show More button can be displayed at the bottom of the list to load additional posts.

Depending on the use case and the performance, each app team must decide for itself how many entries should be shown before the Show More button appears.

When the user clicks or taps Show More, a predefined number of additional posts is loaded. The relative position of the timeline must not change, so the same posts are visible in the same screen position after the additional entries have been loaded.

Behavior – Show More
Behavior – Show More

Grouping

The timeline allows applications to group posts by certain criteria, such as by year. Groups can be expanded and collapsed in order to get a better overview.

The following example shows a collapsed group (Posts from 2016) and an expanded group (Posts from 2015).

Interaction – Grouping
Interaction – Grouping

Custom Actions

App developers can introduce custom actions that can be performed on a timeline post. These actions should be kept to an absolute minimum since they will appear in the limited space next to the social actions (see point 4 in the Layout section above).

In the example opposite, the custom actions Edit (1) and Delete (2) have been added to the post.

Behavior – Custom actions Edit and Delete
Behavior – Custom actions Edit and Delete

In this next example, the custom action Download (3) enables the user to quickly download an attachment directly from the post.

Behavior – Custom action Download
Behavior – Custom action Download

Refresh

Instead of showing new posts as soon as they arrive (which would disrupt the user’s reading), the timeline offers a very subtle way of notifying users about new posts.

App developers can place a message strip directly below the toolbar to show how many new posts can be retrieved from the backend.

Behavior – Refresh
Behavior – Refresh

The message strip works seamlessly together with the timeline’s filter.

Behavior – Refresh and Filter
Behavior – Refresh and Filter

Styles

There are various layout options. When you choose the layout, consider the type of content and the screen real estate available for displaying the control.

 

Orientation

  • Vertical
    Use the vertical timeline for narrow containers or on smartphones (in portrait mode).
Styles – Vertical with icons
Styles – Vertical with icons
Styles – Vertical without icons
Styles – Vertical without icons
  • Horizontal
    You can use the horizontal timeline on wide screens, the object page, or even on smartphones in landscape mode.

You can display both the vertical and horizontal timelines with or without icons.

Styles – Horizontal with icons
Styles – Horizontal with icons

Colors

You can use colors to highlight entries in the timeline and indicate semantic meanings (for example, to indicate the status or urgency of an entry).
Styles – Timeline with icons and semantic colors
Styles – Timeline with icons and semantic colors

Guidelines

  • In narrow containers, use the vertical orientation.
  • In wide containers with little height, such as on the object page, use the horizontal orientation.
  • Only use the speech bubble icon for posts entered manually by users:  
    CSS name: icon-post
    HTML Unicode: & # xe 0 a b ; (remove the spaces)
  • Do not use colors for decoration. Colors are to be used for semantic meaning only (such as for warnings or errors).

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

Implementation

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 time 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)
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.

Time picker input
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 and minutes
Dropdown with hours, minutes, seconds, and AM/PM
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.

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. For example, 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.

Time picker dropdown and input field
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 time by swiping up and down
Set time by swiping up and down

Style

Disabled Time Picker

In the disabled state, the time picker input is grayed out and the button becomes invisible.
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.
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

Implementation

Carousel

The carousel allows the user to browse through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

Optionally, a paging indicator displays the user’s current position inside the set of items.

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

The size of the control’s content area is automatically adjusted to the amount of space available.

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed either floating above the left and right side of the content area or in the paging indicator area. This is controlled by the arrowsPlacement property.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

When the item set contains only one item, the navigation is deactivated.

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

The carousel can be set to loop (property: loop). In this case, the carousel jumps back to the first item once all items have been displayed. If looping is not enabled, there is no forward navigation on the last item.

Paging

The current position inside the set of items is displayed using an optional paging indicator (properties: showPageIndicator, pageIndicatorPlacement).

Paging indicator
Paging indicator

If there are more than 8 pages, the paging indicator changes from icons to numbers.

Paging indicator
Paging indicator

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

Image (guidelines)

Implementation

Breadcrumb

A breadcrumb (or breadcrumb trail) is a type of secondary navigation that indicates the position of a page in its application hierarchy, specifically in a drilldown scenario of object pages, tables, and charts.

Usage

Use a breadcrumb if:

  • You want to show secondary navigation on the object page.
  • You want to show navigation in a table.
  • You want to show navigation in charts.

Use a breadcrumb only in drilldown scenarios to related object pages, such as: Parent object page/Child object page 1/Child object page 2/Child object page 3.

Do not use a breadcrumb if:

  • You only have one level in your hierarchy.

Other instances:

  • Do not include other floorplans like overview pages and list reports in the breadcrumb path.
  • Do not include cross-application navigation to other object pages in the breadcrumb path.
  • Do not include standalone object pages like fact sheets in the breadcrumb path.

The above cases are covered in the global navigation concept for SAP Fiori 2.O.

Responsiveness

Breadcrumbs are responsive. If there is insufficient horizontal space, the links of the breadcrumb trail start to collapse into a dropdown menu (sap.m.Select) as follows:

  • The first link in the breadcrumb (the point of origin) collapses first, followed by the next link in the hierarchy.
  • The last element in the breadcrumb is always visible.
  • The last element should never collapse into the dropdown.
  • If there is insufficient horizontal space for the last element in the breadcrumb, text is truncated to fit the available screen real estate.
Breadcrumb – Size L
Breadcrumb – Size L
Breadcrumb – Size M
Breadcrumb – Size M
Breadcrumb – Size S
Breadcrumb – Size S
Breadcrumb – Size S (dropdown menu selected)
Breadcrumb – Size S (dropdown menu selected)

Layout

The horizontal layout of the breadcrumb never changes. The links always appear next to each other.

Types

There are two types of breadcrumbs:

  1. Standard breadcrumb.
    The standard breadcrumb shows the current page as the last item in the trail. This is the only item that is not a link, but plain text.
  2. Breadcrumb without the current page. Use this breadcrumb only on the object page.
    The breadcrumb shows the page’s position in the site hierarchy without the current page. All items in the breadcrumb are links.
Standard breadcrumb
Standard breadcrumb
Breadcrumb without the current page
Breadcrumb without the current page

Components

The breadcrumb can contain links and text or just links, depending on the type.

Behavior and Interaction

Navigation

The purpose of the breadcrumb is to trigger navigation. The action is triggered when the user clicks or taps a link in the breadcrumb trail.
For link behavior and interaction, see the article on links.

Styles

For information about the various styles of links, see the article on links.

Guidelines

  • In the dropdown menu on desktops and tablets, show only the links that are not visible in the breadcrumb trail.
  • In the dropdown menu on smartphones, show all the links in the breadcrumb trail in their hierarchical order.

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

Implementation

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 S/M
Step input - size L
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
Step input areas

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.

Minimum and Maximum Values

App developers can set a maximum and minimum value for the step input.

When reaching the maximum/minimum values, the increase/decrease button and up/down keyboard navigation are disabled.

Step input at maximum value (max = 100)
Step input at maximum value (max = 100)
Step input at minimum value (min = -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
Default state
Warning state with value state text
Warning state with value state text
Error 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

Minimum

Sets the minimum possible value of the defined range.

Maximun

Sets the maximum possible value of the defined range.

Step

Increases/decreases the value of the input. The step can be a floating-point value.

Larger Step

Increases/decreases the value with a larger value than the set step (only when using keyboard shortcuts). The default value is two times larger than the set step.

Value

Determines the value of the step input. App developers can set default initial value.

Width

Determines the width of the control.

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
Default state
Warning state
Warning state
Error 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
Read-only state
Disabled 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

Implementation

Message Box

The message box (sap.m.MessageBox) is a special dialog that allows you to display messages to the user. Compared to the message popover (sap.m.MessagePopover), you can use the message box to display messages that are not related to a field on the UI, such as technical errors.

Formulate messages in plain language (no code), describe the issue precisely, and suggest a constructive solution. Always help your user to recognize, diagnose, and recover from messages. Bear in mind that no message is always preferable to even a good message. When you design your apps, aim to prevent problems from occurring in the first place.

Usage

Use the message box if:

  • You want to display non-field-related messages.
  • You want to interrupt the user while he or she performs an action.
  • You want to display error, warning, success, confirmation, or information messages.
  • You need to interrupt the user for some other reason.
  • You need the user to acknowledge the message.
  • You need the user to make a decision.

Do not use the message box if:

  • You want to display a short success message. (Use a toast instead. For more information, see message toast.)
  • You can show the message directly in a form field.

Responsiveness

The sap.m.MessageBox control has the same responsive behavior as the sap.m.Dialog control. The message box should only be opened in modal mode. Its basic width is 25 em. For more information, see dialog.

Types

The following categories of messages are available:

  • Error
  • Warning
  • Success
  • Information
  • Confirmation

Error Message

Error messages can be triggered after the user has entered incorrect data or a system error has occurred. They should interrupt the user by displaying a dialog. A final action such as Submit cannot be carried out until the user has rectified the error.

Control: sap.m.MessageBox
Icon: sap-icon://message-error
Title: Error
Stretch: False (no full screen on all devices)

Error message box with one action
Error message box with one action
Error message box with two actions
Error message box with two actions

Text guidelines for an error message:

  • Do not just describe the problem; tell the user how to resolve it.
  • In the short text, speak the language of the end user. Do not include system or configuration details.
  • If the solution is more involved or technical, add a long text.
  • Do not repeat the short text in the long text. They both appear together on the screen.

Warning Message

Warning messages highlight potential issues, but the user can still continue. This includes unintended data loss scenarios.

Control: sap.m.MessageBox
Icon: sap-icon://message-warning
Title: Warning
Stretch: False (no full screen on all devices)

Use cases for warnings

a) No decision required: Formulate the message as a statement.
Button(s): OK

Warning message box with OK button
Warning message box with OK button

b) Decision to continue required: Formulate the message as a statement.

Button(s): OK, Cancel

Warning message with OK and Cancel buttons
Warning message with OK and Cancel buttons

c) Specific decision required, with one action

Use a relevant action button. The message may also be formulated as a question.
Button(s): Leave Page, Cancel

Warning message with action and Cancel buttons
Warning message with action and Cancel buttons

Success Message

Success messages give feedback to the user that an action has been executed. The user needs to acknowledge the message.

Control: sap.m.MessageBox
Icon: sap-icon://message-success
Title: Success
Stretch: False (no full screen on all devices)
Button(s): OK

Success message box
Success message box
Information
You should generally use a message toast (sap.m.MessageToast) to display success messages instead of a dialog (sap.m.Dialog).

Information Message

Information messages provide information the user needs to acknowledge, but which does not involve a decision. The message provides information that is useful and relevant, but never critical.

Control: sap.m.MessageBox
Icon: sap-icon://message-information
Title: Information
Stretch: False (no full screen on all devices)

Button(s): OK

Information message box
Information message box

Confirmation Message

Confirmation messages prompt users to confirm an action that they have triggered. The title of the message box already includes the action that has to be confirmed, such as an intended deletion or an approval.

Control: sap.m.MessageBox
Icon: sap-icon://message-question
Title:  (such as “Approve”, “Reject”, or “Delete”)
Stretch: False (no full screen on all devices)

Button(s): Approve, Cancel

Confirmation message box – Approve
Confirmation message box – Approve

Confirmation Message with “Note” Section

Warning
The image belows shows a “Note” section which allows the user to add notes, for example in a “Reject” process. This feature is not provided by the sap.m.MessageBox. Instead, you can use a normal sap.m.Dialog and place those controls inside the confirmation message.

Confirmation messages prompt users to confirm an action that they have triggered. The title of the message box already includes the action that needs to be confirmed, such as an intended deletion or an approval.

Control: sap.m.Dialog
Type: Message
Icon: sap-icon://message-question
Title:  Such as “Approve”, “Reject”, or “Delete”
Stretch: False (no full screen on all devices)

Button(s): Approve, Cancel

Confirmation message box – Reject
Confirmation message box – Reject

Delete Message

If the user clicks or taps Delete, display a “Delete” dialog that confirms the delete action.

Control: sap.m.MessageBox
Icon: sap-icon://message-warning
Title: Delete
Stretch: False (no full screen on all devices)

Button(s): Delete, Cancel

Delete message box
Delete message box

Components

Show Details button

The message displayed for the user should provide sufficient information to ensure that the user knows what has happened. A message box without an explicit details section should be sufficient. Therefore, the Show Details link is only shown if detailed information is available that differs from the message text and is important for the user.

If details are available, the application has three option to display the text. Text can be displayed as:

  • Plain
  • Formatted
  • The original code format
Plain details text
Plain details text
Formatted details text
Formatted details text
Show details button on a message dialog
Show details button on a message 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

Implementation

Popover

The popover displays additional information for an object in a compact way and without leaving the page. The popover can contain various UI elements such as fields, tables, images, and charts. It can also include actions in the footer.

Note: The quick view is similar to a popover, but has a predefined structure, a fixed set of UI elements, and automatic UI rendering. Check first whether the quick view is appropriate for your use case. For more information, see quick view.

Usage

Use a popover if:

  • You need to define your own structure.
  • You want to show UI elements that are not available with the quick view.

Do not use a popover if:

  • The quick view is more appropriate for your use case.
  • The objects are in a master list (in this case, the details are shown in the details area).

Responsiveness

The popover can be used in the following ways:

  • Responsive and adaptive: sap.m.ResponsivePopover
    Shows a dialog on smartphones (to be closed with an X) and a popover on a tablet or desktop.
  • Non-responsive: sap.m.Popover
    Always shows a popover. Only use a non-responsive popover if it has very little content. On smartphones, the popover should not use more than a third of the phone’s real estate.

Layout

Structure of Popover

The header and footer are generally optional. The other elements are as follows:

Back (1) – optional
Needs to be implemented if the user can trigger further popovers. Always show popovers in place. Never place them on top of each other.

Title (2)
We recommend that you show an app-specific title for accessibility reasons. If you do not show a title, use the invisible text control (sap.ui.core.InvisibleText) to set a text for screen reader support.

Close function (3)
This feature closes the dialog. It is available for smartphones only and is set automatically (sap.m.ResponsivePopover).

Content (4)
Ensure that the content has a basic design and shows only the most important information. We recommend the following:

  • Use no more than two groups.
  • Limit the total number of fields to eight.
  • Use single-column tables.
  • Use micro charts.

Actions (5) – optional

Popover – General structure
Popover – General structure
Popover – Example
Popover – Example

Behavior and Interaction

Opening a Popover

The user opens a popover by clicking or tapping an object represented by a text link or an icon. To improve accessibility, we recommend using texts, such as the name or ID of an object.

Closing a Popover

The popover is closed when the user clicks or taps outside the popover or selects an action within the popover.

Guidelines

  • Show status information as text fields in a content group. You can use semantic text colors.
  • You can define a height for the popover. If the content exceeds the height, a scroll bar is displayed.

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

Implementation

Busy State

You can set a busy state for each SAPUI5 control. This function adapts to the space available on the UI.

Usage

Use the busy state of the control if:

  • The operation takes more than one second (busy state set at control level)
  • You want to indicate that data is loading on a table or on a list after performing a search or filtering (set the busy state at table or list level).

Do not use the busy state if:

  • The operation lasts less than one second.
  • You expect several busy states at once. In this case, consider setting the busy state at a higher level or container.
Busy button
Busy button
Busy button - Small
Busy button - Small
Busy form
Busy form
Busy list
Busy list

Guidelines

Avoid showing multiple busy states at once. If you expect multiple busy states on various controls, you can set the busy state on a control or container above.

In some cases, however, it makes sense to allow multiple busy states. For example, a page could contain a form and several tables that load asynchronously. In this case, it does not make sense to set the busy state at page level until all the data is loaded as the user can start filling out the form which is already available. Response times may vary due to table data retrieval from different services.

Try to enable as much as possible on one screen,so the user can start working while the rest of the data is being loaded in the background. Set the busy state for those UI elements that will require some time to load.

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

Implementation

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. Each button shows a dropdown list icon.

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

If the app does not offer all three sorting, filtering, and grouping functionalities, but only one of these (such as sort), we recommend placing the icon button directly in the toolbar.

Do not place sort, filter, or group buttons in the footer toolbar if they refer to a table.

Place group, sort, and filter buttons in the footer toolbar if they refer to a master list.

For detailed information about where to place the sort, filter, and group buttons, see “Sort, Filter, Group (Generic)” in the Behavior and Interaction section of 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 dropdown list icon button in the table header
The dialog is triggered by the dropdown list icon button in the table header
View settings dialog on a smartphone (size S)
View settings dialog on a smartphone (size S)
View settings dialog on a tablet (size M)
View settings dialog on a tablet (size M)
View settings dialog on a desktop (size L)
View settings dialog on a desktop (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 leads the user to detailed filter selection lists via drilldown.

The dialog for choosing a category from the filter tab drills down to the filter settings.
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: Price). The dialog can offer a specification of that category depending on the use case.
The dialog after choosing a general filter category (here: Price). The dialog can offer a specification of that category depending on the use case.
A table view filtered by Price – the info bar shows the filter setting.
A table view filtered by Price – 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.

Multi-selection of filters
Multi-selection of 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.

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.

Removing Filters

Be sure to offer an entry such as None in a single-selection list which removes a set filter.

The dialog for choosing an attribute from the group tab.
The dialog for choosing an attribute from the group tab.
A table view grouped by suppliers – group headers divide the list.
A table view grouped by suppliers – 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.

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

Implementation

Busy Indicator

The busy indicator informs the user about an ongoing operation.

Busy indicator - Medium and Large
Busy indicator - Medium and Large
Busy indicator - Small
Busy indicator - Small

Usage

Use the busy indicator if:

The ongoing operation covers only a part of the screen with multiple controls, and:

  • you need to display additional information, or,
  • the user needs to be able to cancel the operation.

Take a look at the example on the right. The file upload dialog consists of multiple upload operations. The user must be able to cancel each operation. Since the operation is related only to one row and not to the full app, there is no need to block the whole screen. The user still needs to interact with the system, in this case to select the next file upload.

Since each control of SAPUI5 provides a busy state by default, you could also set the busy state at row level. In this case, however, there would be no option to cancel the operation.

Busy indicator example file upload
Busy indicator example file upload

Do not use the busy indicator if:

  • The operation takes less than one second.
  • You need to block the screen because the user is not supposed to start another activity. In this case, use the busy dialog.

Components

The busy indicator is a blue circle and can also display a text description.

Busy indicator text
Busy indicator text

Guidelines

  • Do not change the mouse cursor to indicate the ongoing operation.
  • Do not use a custom progress indicator icon.
  • Try to avoid showing multiple busy indicators at once.

Properties

The size of the busy indicator can also be changed.

Busy indicator sizes
Busy indicator sizes

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

Implementation

Info Bar

The info bar is a type of toolbar that appears above a list or panel, and shows filter or selection settings:

  • Filter criteria: The info bar indicates the filter criteria that have been applied for a filter or contextual filter. Do not show the info bar if no filter is applied.
  • Selected items: In a multi-select dialog, the info bar shows the number of selected items.
Info bar is placed above the content and shows the applied filters.
Info bar is placed above the content and shows the applied filters.

Responsiveness

The bar has the same height, text size, and icon size in both cozy and compact formats. The text inside the bar will be truncated if there’s not enough space.

Text is truncated on a small screen. The example shows an info bar for a contextual filter.
Text is truncated on a small screen. The example shows an info bar for a contextual filter.

Types

There are three situations in which an info bar is shown:

  1. After a general filter has been applied.
  2. After a contextual filter has been applied.
  3. After the user has selected multiple items in a select dialog.

General Filter

All applied filters are shown as labels in the info bar.

Info bar after a filter has been applied
Info bar after a filter has been applied

Contextual Filter

The contextual filter allows the user to see a prefiltered view of a list. The title on the left side and an icon on the right side display the filter criteria. The Filter icon should represent the filter category. Do not use a generic filter icon, otherwise it may be confused with the user-triggered filters. For more information, see contextual filter.

Info bar after a contextual filter has been applied
Info bar after a contextual filter has been applied

Multiselection

If the user selects multiple items, the info bar shows the number of selected items. For more information, see select dialog.

Info bar after multiselection has been applied
Info bar after multiselection has been applied

Components

The info bar is a toolbar that consists of a label on the left side and an icon on the right side.

The label shows the filter criteria, and the icon selected depends on the use case.

General Filter and Multiselection

No icon is shown. The only exception is the Cancel icon, which is used to reset the current filter criteria.

Info bar with optional Cancel icon
Info bar with optional Cancel icon

Contextual Filter

The icon is mandatory and represents the current filter criterion.

There is one exception in which it is useful to be able to cancel the contextual filter. In this special case, the contextual filter is used to prefilter the listed items in a select dialog. For this case, use the Cancel icon instead of the Filter icon. For more information, see contextual filter.

In all other use cases, show an icon that represents the filter criterion.

Contextual filter with filter icon
Contextual filter with filter icon

Behavior and Interaction

The bar can have two active areas: either the entire bar can be active, or if an icon is added, it creates a second active area. We recommend that you use the active behavior for the bar and the icon.

Bar Area

When the user clicks or taps the bar, the filter dialog from the view settings dialog is shown. If only one filter is applied, the filter can be changed directly in the detailed filter selection. If more than one filter is applied, the filter dialog shows a list with general filter categories.

Clicking the info bar with a single filter shows the detailed filter selection.
Clicking the info bar with a single filter shows the detailed filter selection.
Clicking the info bar with multiple filters shows the filter categories.
Clicking the info bar with multiple filters shows the filter categories.

Icon Area

  • Cancel: The user clicks or taps the icon to delete the current filter settings. We recommend that you use the cancel icon.
  • Filter (only contextual filter): Clicking the icon has the same effect as clicking the bar. The filter dialog is shown.

Properties

The contextual filter is not a separate control. If you want to build an info bar, you need to use the sap.m.toolbar control. To achieve the info bar design, set the design toolbar property to “info”.

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

Implementation

  • No links

Chart – Semantic Patterns

This article explains how to use patterns like dashes, dots or hatches in order to distinguish:

  • Actual Values: What values are (solid pattern).
  • Projected Values: What values might be (dashed line, hatched areas).
  • Reference Values: What values should be (dotted line with empty circles, empty areas).

Actual Values

Actual values register facts that happened in the past and utilize the solid pattern for areas and lines, as illustrated below.

Line chart with actual values
Line chart with actual values
Column chart with actual values
Column chart with actual values

Projected Values

Projected values are estimates of what might happen in the future such as a forecast, estimation or prediction. They indicate what the actual values will be in the future, and the projection can be calculated by the system, extrapolated from previous time periods, or entered manually by a user.

Example:

  • Revenue forecast calculated from previous months.
  • Adjusted revenue forecast that has been manually adjusted based on the current context.
  • Cost for projects that are committed, but not yet delivered.

Dashed Line

Use dashed lines to show projected values as illustrated below.

Line chart with actual and forecast values
Line chart with actual and forecast values

A line can change from solid to dashed when the line needs to display actual values followed by projected values. In the example below, the line connecting the last actual value (2015) to the first projected value (2016) is dashed to indicate that the line is a projection.

Line chart with actual values followed by forecast values
Line chart with actual values followed by forecast values

Hatched Area

Use the hatched pattern in columns and bars to display projected values, as illustrated below.

Column chart with actual and forecast values
Column chart with actual and forecast values
Stacked bar chart with actual and forecast values
Stacked bar chart with actual and forecast values

A series of columns with the solid pattern can be followed by a series of columns with the hatched pattern when a series displays actual values followed by projected values, as illustrated below.

Column chart with actual values followed by forecast values
Column chart with actual values followed by forecast values
Bullet chart with actual values followed by forecast values
Bullet chart with actual values followed by forecast values

Reference Values

Some values represent a reference for other values (such as a threshold that should be reached or should not be reached) depending on the use case. Here are some examples:

  • A target revenue that must be reached.
  • An expense budget that should not be exceeded.
  • The share price of a competitor to use as a benchmark.
  • The number of new customers acquired last year that needs to be exceeded this year.

The bullet chart is the ideal chart to compare values with reference values. The reference value is displayed by the black horizontal lines as illustrated in the chart below.

Bullet chart with actual and target values
Bullet chart with actual and target values

Dotted Line and Empty Circle

Reference values displayed as a line should use a dotted line and empty circles for the data points as illustrated below.

Line chart with actual and target values
Line chart with actual and target values

When there are many data points, the circles are automatically hidden, as illustrated below.

Line chart with plenty of actual and target values
Line chart with plenty of actual and target values

When the chart contains one actual value and one reference value (such as a target), you should use color sapUiChartPaletteSequentialNeutralDark2 for the reference line and the first color from the qualitative palette for the actual value, as illustrated below.

Colors used in a line chart with actual and target values
Colors used in a line chart with actual and target values

When the chart combines a single reference value (such as a target) with multiple actual values, you should use color sapUiChartPaletteSequentialNeutralDark2 for the reference line and colors from the qualitative palette for the actual values, as illustrated below.

Line chart with one single target value for multiple actual values
Line chart with one single target value for multiple actual values

When the chart contains multiple pairs of actual values and reference values, you should use the same color for each pairs. The pattern will make the difference. Use the first colors of the qualitative palette:

sapUiChartPaletteQualitativeHue1, sapUiChartPaletteQualitativeHue2, sapUiChartPaletteQualitativeHue3…

Line chart with multiple pairs of actual and target values
Line chart with multiple pairs of actual and target values

When the reference values and the actual values do not have a direct relationship, you should use colors from the qualitative palette and all the lines should all have different colors, as illustrated below.

Line chart with multiple actual values and multiple target values
Line chart with multiple actual values and multiple target values

Empty Area

When columns or bars are used to display reference values (such as a target, plan or budget), you should use the empty pattern.  You should also use the color sapUiChartPaletteSequentialNeutralDark2 for the reference value and the first color from the qualitative palette for the actual value as illustrated below.

Column chart with actual values and target values
Column chart with actual values and target values

When the chart contains a reference value (like a target) for multiple actual values, you should use color sapUiChartPaletteSequentialNeutralDark2 for the reference value and colors from the qualitative palette for the actual values, as illustrated below.

Column chart with one single target value for multiple actual values
Column chart with one single target value for multiple actual values

When the chart contains multiple sets of linked actual values and reference values, you should use the same color for each pairs. The pattern will make the difference. Use the first colors of the qualitative palette: sapUiChartPaletteQualitativeHue1, sapUiChartPaletteQualitativeHue2, sapUiChartPaletteQualitativeHue3…

Column chart with multiple pairs of actual and target values
Column chart with multiple pairs of actual and target values

When multiple reference values and multiple actual values do not have a direct relationship, you should use colors from the qualitative palette.  Columns for the reference values and columns for the actual values should all have different colors, as illustrated below.

Column char with multiple actual vales and multiple target values
Column char with multiple actual vales and multiple target 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

Implementation

Analytical Card

The analytical card is used for data visualization. It consist of two areas – a header area (either a standard header or a KPI header) and a chart area that displays a visual representation of the data. It is a single object card and does not contain a footer area. The analytical card can only be used in the overview page (OVP).

Responsiveness

The analytical card has a uniform horizontal width of either 20 or 25 rem, depending on the screen size. The vertical height is flexible. The VizFrame charts within the cards are fully responsive.

Header Area

There are two header types that could be used with the analytical card depending on the use case:

Standard Header

  • Title (mandatory): The title symbolizes the most important information. We recommend using a single-line text, but it is possible to wrap the title to two lines.
  • Subtitle (optional): The subtitle can be wrapped up to two rows and will get truncated at the end of the second line. If the subtitle contains multiple qualifiers, separate them with comma. Do not repeat the chart title here.
Standard header
Standard header

KPI Header

  • Title (mandatory): The title symbolizes the most important information. We recommend using a single-line text, but it is possible to wrap the title to two lines.
  • Subtitle (mandatory): The subtitle can be wrapped up to two rows and will get truncated at the end of the second line. The unit of measure is shown at the end of the subtitle. For this reason, we recommend keeping the subtitle short and within one line. If the subtitle contains multiple qualifiers, separate them with comma. Do not repeat the chart title here.
  • KPI area, containing the following elements:
    • Trend arrow (optional)
    • KPI value (mandatory) – The KPI value uses semantic colors
    • Percentage symbol (optional)
    • Value selection information (optional) – Manually-entered text to provide a better description of the key value (for example, Number of Products). It can be used in case the sorting information and the filters do not provide enough information to properly describe the value. This text will become truncated after one line.
    • Sorting information (mandatory) – Describes the KPI/value.
    • Filters (optional) – Can be modified to show meaningful text.
    • Target and deviation (both mandatory) – They could be a relative or absolute value.
KPI header
KPI header

Types

There are eight chart types currently supported by the analytical card:

 

Information
You can find additional information about the different chart types, as well as tips for choosing the correct chart type, in the following articles:

Line Chart

In general, the line chart is the most efficient chart for showing the evolution of a trend over a period of time.

  • Avoid showing more than four lines in the same card.
  • When showing more than one line in the chart, different units should not be displayed. All the lines should use the same unit, such as “Euro”.

Use the line chart if…

  • You want to emphasize the evolution of a trend over a period of time.
  • You want to visualize data that contains an intrinsic order, such as age, a range, or a rating (but excluding time). In this case, there is an idea of a progression or trend, and the best way to represent these values is to use the horizontal axis.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Do not use the line chart if…

  • You want to emphasize the values themselves. Use a column chart instead.
  • The data does not contain an intrinsic order.

Analytical card with line chart and view switch
Analytical card with line chart and view switch

Bubble Chart

A bubble chart displays the correlation between three sets of numerical values. One set is represented in the horizontal axis, another set is represented in the vertical axis, and the third set is encoded in the size of the bubbles.

We recommend showing only one or two series. Because series are represented by specific bubble colors, having too many series/colors can make the chart hard to read.

The sizes of the bubbles are determined by the values in the third data series. The measure that is represented by the bubble size is defined below the chart.

Color

  • If the goal is to isolate outliers within a cloud of other bubbles, use the same color for all bubbles.
  • If the goal is to group bubbles that have the same characteristic, use one color per group. Warning: Too many colors can make the chart hard to read.
  • If the goal is to compare bubbles individually, then use one color per bubble. Only use this option if there are very few bubbles.

Use the bubble chart if…

  • You need a rough approximation of the values encoded in the bubble size.
  • You want to represent data with three dimensions on a 2D chart.
  • You want to compare and show the relationships between labeled/categorized circles, by the use of positioning and proportions.
  • You want to display the correlation between three sets of numerical values.

Do not use the bubble chart if…

  • You need to represent information only with two dimensions.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with bubble chart
Analytical card with bubble chart

Column Chart

Column charts are used to compare multiple values over time or over values containing an intrinsic order (such as age).

Columns are clustered side-by-side along the horizontal axis and are color-coded by series.

  • We recommend using no more than two series and a maximum of four category items.
  • If you want to show the trend over time of two series, you can use the line chart with two lines instead of two series of columns.

Use the column chart if…

  • Category items represent a time series. The natural orientation for time is from left to right.
  • Category items contain an intrinsic order. For example, age, range, and ranking.
  • You want to emphasize the values themselves rather than the trends.

Do not use the column chart if…

  • Your data is not related to a time category or to a category with an intrinsic order.
  • You want the emphasis to fall on the trend. Use the line chart instead.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

For more detailed information, see column chart.

Analytical card with column chart
Analytical card with column chart

Stacked Column Chart

This type of visualization depicts items stacked on top of one other in columns, with the item categories differentiated by colored bars or strips.

This chart works only for time series and categories with an intrinsic order.

Use the stacked column chart if…

  • You want to display variation of the sum of measures over a period of time.
  • The sum of the values is as important as the individual items.

Do not use the stacked column chart if…

  • Accuracy or comparisons are of primary importance. In this case, a line graph might be the better option.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with stacked column chart
Analytical card with stacked column chart

Vertical Bullet Chart

The bullet chart is used to compare a primary value to a secondary over time or over a category containing an intrinsic order, such as age, range, or ranking.

The bullet chart supports primary values, comparison values and additional values. For more information, see bullet chart.

Use the bullet chart if…

  • You want to compare a primary value to a secondary value using a reference point. For example, if you want to compare actual and planned costs per quarter.
  • The category items represent a time series. The natural orientation for time is from left to right.
  • The category items contain an intrinsic order.

Do not use the bullet chart if…

  • Your data does not contain an intrinsic order.
  • You have only one series of data.
  • There is no data series that act as a reference point for the other data series.
Analytical card with bullet chart
Analytical card with bullet chart

Donut Chart

The donut chart is used to represent parts of a whole, and the whole should always represent 100%. The data is displayed in rings, where each ring represents a data series.

We recommend using a maximum of four sections in the donut chart. If there are more than four sections in the chart, the ‘Others’ section can be used. It merges several sections into one. The number of all sections included in ‘Others’ is mentioned in the legend item.

The donut chart provides the ability to display percentage next to each section in the chart.

Use the donut chart if…

  • You want to visualize the part to whole as a percentage.

  • You have one or more category items that you want to plot.

Do not use the donut chart if…

  • You want to plot negative or zero values.
  • You have more than four categories or sections.
  • You want to compare data over time. You can use the column chart, line chart, stacked column chart, or bullet chart instead.
Analytical card with donut chart
Analytical card with donut chart

Combined Column and Line Chart

Combined column and line charts are used to compare two sets of values over time or over a category containing an intrinsic order, such as age, range, or ranking.

You could also use a column chart or a line chart for that, but using a combined column and line chart is the better choice if you want to clearly distinguish between the two sets of values, or if the values represent different measures, such as revenue and profit.

Use the combined column and line chart if…

  • You want to compare values in different categories.

  • You want to give a clear view of which category is higher or lower.

  • You want to use more than one measure.

Do not use the combined column and line chart if…

  • The combination data between line and column is not logical.

Note: For time series, we recommend using the time axis. See the section Guidelines (Time Axis) in this article for more information.

Analytical card with combined column and line chart
Analytical card with combined column and line chart

Scatter Plot Chart

A scatter plot chart is a type of chart that displays the correlation between two sets of numerical values. The data is displayed as a set of points plotted on a horizontal and vertical axis.

We recommend showing only one or two series. Because bubbles in a series are color-coded, having too many series/bubbles can make the chart hard to read.

Use the scatter plot chart if…

  • You want to show the correlation between two sets of numerical values (for example, the correlation between age and income).

Do not use the scatter plot chart if…

  • You want to show the correlation between three sets of numerical values. Use the bubble chart instead.
Analytical card with scatter plot chart
Analytical card with scatter plot chart

Behavior and Interaction

The entire header area of the card is selectable. It serves as navigation to the specific app or view from which the card content originates. If the application needs to show detailed information about a specific data point, the single selection mode can be used. It is up to the app developer to provide meaningful navigation.  For example, clicking/tapping on a section from the donut chart can navigate the user to an object page providing more information.

There are two selection modes for the charts: single selection and no selection. Clicking or tapping a blank area on the chart does not trigger any action.

Single Selection

In the single selection mode, clicking or tapping a data point selects the data point and navigates to a more detailed screen.

No Selection

In this mode, data points cannot be selected individually and therefore no actions can be triggered from a data point.

Guidelines

Number of Data Points

There is no technical limitation regarding the number of data points, but be aware that the user experience can be very degraded when there are too many data points. For example, labels in the horizontal axis will be displayed at 450. In the bubble chart, too many bubbles might lead to unreadable information.

Chart Title

The chart title is always visible for each chart type. It is used to describe the axis titles within the chart. The chart title is constructed by the measures and dimensions used in the chart. For example, Revenue by Quarter conveys that the y-axis represents the revenue and x-axis represents the quarters. The title will get truncated at the end of the line.

Time Axis

The time axis is more responsive and shows information in much better manner compared to the category axis. Currently the time axis is supported for the line, column, stacked column, bubble and combination charts. You could use these chart types either with the category or with the time axis. We recommend using the time axis when the category items represent a time series.

The time axis has three main advantages:

  • It allows you to display dates and times in a responsive manner.
  • All the complexity involved with formatting the axis labels is automatically taken care of.
  • The physical spacing between the data points accurately represents the time scale, as opposed to being equidistant.

Axis Title

The axis titles are always hidden, except in the bubble and scatter plot charts. For those charts, use the chart title of the analytical card to convey this information. For example, Revenue by Quarter conveys that the y-axis represents the revenue and x-axis represents the quarters.

Axis Labels

Try to avoid displaying labels at 450. Use abbreviations for dates, such as Jan or Feb for months, or Q1 or Q2 for quarters.

Semantic Patterns

The analytical card supports semantic patterns, such as dashes, dots, or hatches, in order to distinguish:

  • Actual values: What values are (solid pattern).
  • Projected values: What values might be (dashed line, hatched areas).

Currently, semantic patterns are supported for the following chart types: line chart, column chart, and vertical bullet chart.

Semantic Colors Based on Values

Use semantic coloring based on values when you want to show data points that are positive, neutral, or negative. Based on the defined threshold values, the color of each data point could be red, green, or orange. For more information on color use, see colors.

Legend

Colors are automatically assigned and cannot be customized.

View Switch

The view switch functionality provides the user with different views of the data in one card. It can be used for filtering, sorting, or grouping (such as by supplier or material group). The view switch is optional.

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

Implementation

  • No links.

Responsive Table

The responsive table is the default table in SAP Fiori. It contains a set of line items and is fully responsive. Depending on the scenario, users can also navigate from the line items to further details.

A line item contains several data points sorted into columns. A data point refers to a unit of information, such as a number, a text, a unit of measurement, and so on, which can be used to form the content of a table, form or other control. One data point is usually displayed by a control, such as a text, object status, or input field. A control can display more than one data point, for example, by concatenating text.

In contrast to traditional tables, a “cell” of the responsive table is not limited to displaying only one control, and therefore a single cell can present far more than one data point.

Responsive table
Responsive table

Usage

Use the responsive table if:

  • You need a table. The responsive table is the default table in SAP Fiori.
  • You need to use various controls inside a line item, such as micro charts, for example. In contrast, the analytical table supports only a very limited set of controls.
  • The focus lies on working on line items, not on cells. The responsive table is optimized for viewing complete items on all devices.
  • Selecting one or more items is a main use case and details are needed to choose the correct item.
  • Line items are independent of each other and no operation across columns is needed.
  • You want to have only one implementation for all devices. As the name suggests, the responsive table is responsive.

Do not use the responsive table if:

  • The main use case is to select one item from a very small number of items, without viewing additional details. In this case, a select or combo box might be more appropriate.
  • The main use case is to select one item from several items, with the possibility of viewing only a few details per item. In this case, a list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance. The master list is a good example of a list use case.
  • The cell level and the spatial relationship between cells is more important than the line item. In this case, use the analytical table or grid table. Examples include spreadsheet analyses and waterfall charts. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You are working on more than 1,000 rows. In this case, the analytical table and the grid table are easier to handle and provide better performance. In contrast to the responsive table, the architecture of the analytical table and of the grid table is optimized for handling large numbers of items. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • Comparing items is a major use case. In this case, the analytical table or grid table might or might not be more appropriate. Each cell contains only one data point. In contrast, the responsive table has more flexibility in terms of line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that neither the analytical table nor the grid table are fully responsive. Both are only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain children. Note that neither the tree table nor the analytical table are fully responsive. You will need to take an adaptive approach by offering an additional UI for tablets.
  • You need an overview of a large amount of data. In this case, use a chart.
  • You just need it for layout reasons. In this case, use a layout container such as a horizontal layout or a vertical layout instead.
  • You need read-only or editable field-value pairs. In this case, use a form instead. The responsive table is not optimized for form-like input navigation.
Don't
Don't: Do not use a responsive table as a form
Don't: Do not use a responsive table as a form

See the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The responsiveness of a responsive table is optimized for viewing one line item at a time with no or only vertical scrolling, irrespective of the display width.

On smartphones, only the most important data remains in the one-column or two-column table, while all other data is moved to the space between two item rows, known as the “pop-in area”. In this area, data of the corresponding cell is provided as a label, or value pair, which is defined by the column header. The pop-in area itself is responsive, so labels can be shown next to or above the corresponding data.

The responsive table displayed on a smartphone (size S)
The responsive table displayed on a smartphone (size S)
The responsive table displayed on a tablet (size M)
The responsive table displayed on a tablet (size M)
The responsive table displayed in compact mode on a desktop computer (size L)
The responsive table displayed in compact mode on a desktop computer (size L)

To ensure responsiveness, you must configure each column. Depending on the screen width (in pixels), the column needs to know which of the following responses is required:

  • Stay in the table layout.
  • Move to the pop-in (sap.m.Column, with the properties: demandPopin, minScreenWidth, popinHAlign, popinDisplay).
  • Hide.

Since you have to define this for each column, you can also handle more than one column at a single breakpoint, such as moving three columns to the pop-in area at once.

Each of the three device types has a predefined value for the screen width. However, you will get better results if you offer more breakpoints by using pixel values instead of the predefined values.

For the smallest screen width, keep the following information in the table layout:

  • The identifier of the line item
  • The key attribute

The examples in the following tables help to illustrate this:

A typical responsive table.

A typical responsive table
A typical responsive table

Hide the information column for a screen width smaller than 570 px.

Hiding the information column
Hiding the information column

Move the column “vendor” to the pop-in area for a screen width smaller than 460 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the vendor column to the pop-in area
Moving the vendor column to the pop-in area

Move the column “limit” to the pop-in for a screen width smaller than 350 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the limit column to the pop-in area
Moving the limit column to the pop-in area

Move the column “price” to the pop-in area for a screen width smaller than 270 px (sap.m.Column, properties: demandPopin, minScreenWidth).

Moving the price column to the pop-in area
Moving the price column to the pop-in area

If you still need to support smaller screens, values can be moved below the corresponding labels inside the pop-in area. In these examples, this happens for a screen width smaller than 220 px (sap.m.Column, property: popinDisplay).

Pop-in area: moving the data below the labels
Pop-in area: moving the data below the labels

Layout

The optional title bar consists of the title of the responsive table, an item counter, the variant management, and the toolbar.

The filter info bar appears when the responsive table is filtered, and it shows information on the filter settings.

The column header shows the label for each column.

The collection of items, or rows, occupies the main part of the responsive table.

You can add aggregation information (such as totals) on the table footer.

A More button can be shown if you do not want all items to be loaded at the start (known as “lazy loading”). Ideally, you should use scrolling to load more items instead of choosing the More button.

Schematic visualization of the responsive table
Schematic visualization of the responsive table

Components

The title bar consists of the title of the responsive table, an item counter, the variant management, and the toolbar.
The toolbar can contain entry points for the view settings dialog and the table personalization dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.
Beneath the toolbar, display a filter info bar (which itself is a special toolbar) if the responsive table is filtered.
To format data as part of items, apply the guidelines for formatting data. Controls commonly used inside items are the object identifier and the object number. For more information about these controls, please see object display components.
The table footer can be used to display additional static information to the table content.
The More button loads more items to the frontend if not all items are yet loaded.
Components of the responsive table
Components of the responsive table

Behavior and Interaction

The responsive table is quite flexible in regards to its content.

Table Level

Scroll

The height of the table is defined by the numbers of items it contains. It does not have a scroll container on its own, but is scrolled together with the app (in contrast to the grid table and the analytical table).

If the table works in a “growing” mode, it only loads a few items at first. Additional items are only loaded (and rendered) on request. The “request” can either be done via scrolling (preferred), or by clicking the More button.

Same table, different number of items
Same table, different number of items

Merge Duplicates

To simulate the behavior of row spanning, you can merge cells of consecutive rows inside one or more columns automatically if they contain the same value (sap.m.Column, properties: mergeDuplicates, mergeFunctionName).

Use the merge feature if you expect the column to contain duplicate entries, and it makes sense to group them. In the example screenshot, the Supplier, Product, and Dimensions columns reflect a hierarchical structure: Suppliers have products, which in turn have dimensions. Because suppliers typically have multiple products, merging duplicate entries for the supplier column makes the table easier to read. Note, however, that when the user sorts the table by another field, the hierarchy changes and the merged items are regrouped accordingly.

Do not use the merge feature if duplicate entries are not part of the design. If consecutive table rows happen to have the same values at runtime, this alone isn’t a valid reason to group them.

Supplier column merges duplicates in consecutive rows
Supplier column merges duplicates in consecutive rows
Merged columns with multiselection
Merged columns with multiselection

Select

A responsive table can have one of the following selection types (sap.m.Table/ sap.m.ListBase, property: mode):

  • None: Items cannot be selected (sap.m.ListMode.None).
    Beware: Line items can, nevertheless, use the sap.m.ListType “navigation” which allows click handling on specific line items. This should only be used when the click triggers a navigation to a corresponding line item details page.
  • Single select master: One item of the responsive table can be selected. To select an item, the whole row can be clicked. Single select master does not add any visual indication (such as checkboxes or radio buttons) and can therefore not be differentiated from none-selection tables. It only provides a selected state as a light blue background. For single selection, this it the preferred mode (sap.m.ListMode.SingleSelectMaster).
  • Single select left: One item of the responsive table can be selected. For this, the responsive table provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the row shoud trigger something else, such as navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).
  • Multi-select: Allows the selection of one or more items. For this, the responsive table provides checkboxes on the left side of each line item. Select All works via a checkbox on the left of the column header. Select All (de-)selects all items which the user can reach via scrolling (sap.m.ListMode.MultiSelect). With multiselection, responsive tables avoid having checkboxes in the first column.
Responsive table without selectable items
Responsive table without selectable items
Single-selection master
Single-selection master
SIngle-selection left with radio buttons. Use only if row clicks are used for something else, such as for navigation.
SIngle-selection left with radio buttons. Use only if row clicks are used for something else, such as for navigation.
Multiselection
Multiselection

Group

For grouping items, a group header is displayed (sap.m.GroupHeaderLisItem). The group header is not interactive.

Group headers
Group headers

Show Aggregations

Show aggregations (such as totals) on the table footer (sap.m.Column, aggregation: footer).

Do not show aggregations in “growing” mode. It is not clear, if an aggregation will only aggregate the items loaded into the front end, or all items.

Table footer displays aggregated total
Table footer displays aggregated total

Load Items

To show more than 200 items, use the “growing” mode (sap.m.Table/ sap.m.ListBase, properties: growing, growingThreshold, growingScrollToLoad, growingTriggerText). The growing mode allows the user to load only the first few items. Additional items are only loaded (and rendered) on request, which improves performance. The “request” can either be done via scrolling (preferred), or by clicking the More button.

If using the More button, show the number of already loaded items and the total number items below the text More, if possible.

Do not show more than 1,000 items overall, even in growing mode. Use the grid table instead.

Do not show aggregations if the growing mode is used. Also, do not display an item count on the table toolbar if growing mode is used. Use the count on the More button instead.

Load on scroll
Load on scroll

Line Item Level

Delete Single Item Rows

To delete single item rows, use the table in the mode “delete” (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds Delete buttons to each line item. Clicking this button triggers the deletion of the corresponding line item.

Do not use this mode if deleting multiple lines at once is the preferred use case.

Delete is a mode of the responsive table and therefore cannot be used together with single selection or multiselection.

Responsive table in
Responsive table in "delete" mode

Navigate

Because the controls inside line items are handled by the corresponding control behaviors, clicking on an interactive control within a line item does not trigger the navigation event.

To allow navigation from a line item, set sap.m.ListType to “navigation” within the corresponding item (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create indicator at the end of the line (“>”) and the entire line item will become clickable. Clicking on the line triggers the navigation event. Use this to navigate to a new page containing line item details. In rare cases, you can also use the navigation mode for category navigation without navigating to another page.

If no navigation is possible, set sap.m.ListType to “inactive”.

Navigation is a list item type and therefore cannot be used together with “edit”, or in combination with click events for the entire item (“active”).

Navigation indicator
Navigation indicator

Edit Line Items

To allow editing a line item details page, set sap.m.ListType to “detail” within the corresponding item (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an Edit button at the end of the line. Clicking the button triggers 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 in combination with click events for the entire item (“active”).

Edit button
Edit button

Click an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere where there is no interactive control inside the item). Apps can react on the event, such as by opening a dialog(sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).

Active elements do not have a visual indication and can therefore not be differentiated from non-active elements.

Active is a list item type and can therefore not be used together with “navigation” or “edit”. In addition, “active” uses the whole item as a clickable area and therefore cannot be used together with a single-selection table.

Active element
Active element

Cell Level

Showing Information

In contrast to traditional tables (such as the analytical table or the tree table), a cell can contain more than just one line of text.

Several lines of text within one cell
Several lines of text within one cell

Add controls

Aside from textual elements, you can also add any control to a table cell.

Controls inside cells
Controls inside cells
Any control can be placed inside cells
Any control can be placed inside cells

A cell can contain more than one control and more than one data point.

Due to the View Settings dialog, you can sort, filter, and group by each of these data points.

Several controls per cell
Several controls per cell

Guidelines

Table Title

Implement the table title by using a toolbar control.

Use a table title if the title of a responsive table is not indicated in the surrounding area. Do not use a table title if it would just repeat text that is already above the responsive table.

Use a table title if you need the table toolbar. To avoid repeating text, feel free to use generic text as a table title, such as Items.

The item count in the table title displays all visible items which the user can reach via scrolling. Group headers are not counted.

Remove the item count in the table title if there are zero items.

If you use a table title, be sure to include one of the following:

Table title
Table title
  • Or an item count using the following format: Items (Number of Items). For example, Items (2). You can combine an item count with variant management.
  • Do not use an item count together with “growing mode”.
Table title with item count
Table title with item count

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.m.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Table in busy state while loading data
Table in busy state while loading data

Columns – Best Practices

Minimize the number of columns:

  • On a smartphone, use only one or two columns, depending on the content.
  • On a tablet or desktop, use up to three columns if the responsive table is shown in the details area of a split-screen layout. Use about eight columns if using the full screen width, depending on the content.

If the responsive table does not fit on the screen width:

  • Hide columns to reduce the width of the table.
  • Use pop-in areas to show the whole content by increasing the height of the line items (sap.m.Column, properties: demandPopin, minScreenWidth).

At the smallest size, keep the following information in the table layout:

  • The column that identifies the line item.
  • The column that contains the key attribute.

If both of these do not fit on the respective screen width, keep just the column with the line item identifier in the tabular layout.

The responsive table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.m.Column, property: width).

Optimize column width for its initial content (sap.m.Column, property: width). If the content is dynamic, optimize column width for typical content.

If you need more columns than those that fit on a tablet screen (usually five) to fulfill 80% of your main use cases, offer an option to add, remove, and rearrange columns via the table personalization dialog. Before doing so, try to reduce the number of columns, for example, by using several lines per column or by utilizing the pop-in function. See the cheat sheet for an example.

Column Headers – Best Practices

Within the column header, provide a label for each column (sap.m.Column, aggregation: header). The column header label is reused as a label in the pop-in area.

Exception: If the column does not pop in, you can leave out the column header label as long as at least one column still has a column header label.

Use controls that wrap, for example, text (with wrapping enabled). Do not use controls that truncate, such as labels.

Do
Do: wrap column headers
Do: wrap column headers
Don't
Do not: truncate column headers
Do not: truncate column headers

Column headers (sap.m.Column, aggregation: header) usually contain links or text-based controls.

Column headers can also contain other kinds of SAP Fiori controls. However, the column header cannot be aligned vertically, making it difficult to use many controls in the column header. Using other kinds of controls also creates problems with pop-in behavior and could thus lead to accessibility issues. Therefore, exercise caution when using them in a column header.

Accepted: Link as column header text (used rarely)
Accepted: Link as column header text (used rarely)
Accepted if responsiveness is taken into account: Text plus search field
Accepted if responsiveness is taken into account: Text plus search field

Content Alignment

For alignment of cell content, follow the guidelines below (sap.m.Column, properties: halgin, valign, sap.m.ColumnListItem, property: VAlign). Align the column header horizontally according to the content of the cell.

Left-align: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text
Left-alignment of text

Right-align: numbers and amounts, except IDs, to ensure comparability of such figures.

Right-alignment of numbers
Right-alignment of numbers

Right-align: dates and times (to ensure comparability for most formats and locales).

Right-alignment of dates
Right-alignment of dates

In general, center one-word status information and icons:

If there is an icon and text, or if the status contains more than two words in the English language, left-align the entire status column.

Center-alignment of one-word texts
Center-alignment of one-word texts

Vertical alignment:

Top-align where possible to facilitate reading the content on one line.

Do not use top-alignment if it results in a peculiar layout. This usually happens when controls that need more vertical space are combined with text-only controls, such as input fields. In this case, try center-alignment instead and fine tune it until the layout fits.

Do
Do: use top-alignment where possible
Do: use top-alignment where possible
Don't
Do not: rigidly use top alignment if it does not make sense
Do not: rigidly use top alignment if it does not make sense

Content Formatting

The responsive table provides flexibility, including multiline cells, by enabling every control to be put into a cell.

As a key identifier of an item, use an object identifier. Show the key identifier in the first column. For more information, see object display components.

If the screen width is small, do not hide this column or move it to the pop-in area.

Object identifier
Object identifier

Strings with IDs: If the responsive table contains more single-line data, show the ID in brackets after the corresponding string.

This minimizes the line height.

For items with a small line height, place the ID in brackets after the corresponding string
For items with a small line height, place the ID in brackets after the corresponding string

Strings with IDs: If line height is already large, show the ID below the corresponding string. Use the object identifier to do so.

For items with a large line height, place the ID below the corresponding string
For items with a large line height, place the ID below the corresponding string

For status information, use semantic colors on the foreground elements.

For status information on text: If the status is actionable, add a transparent icon button next to the text.

Semantic colors on text
Semantic colors on text

Avoid truncation. Use controls that wrap the text.

For example, use text instead of a label.

Do
Do: wrap text
Do: wrap text
Don't
Do not: truncate text
Do not: truncate text

For editable content, use input fields and other interactive controls within the table cells. If you need edit mode, change your text controls, such as labels, text, and links, to input fields or other appropriate controls as soon as you switch to edit mode, but not before.

You can do this by changing the control or, in more complex cases, by exchanging the whole responsive table.

Interactive controls – In line
Interactive controls – In line

If there is no value for a cell, leave it blank. Do not display text as N/A.

Leave empty fields blank
Leave empty fields blank

Numbering items:

  • If the item number has four digits/letters or less and is equally important as the corresponding description, concatenate the item number with the description and show it in one column.
  • If the item number has five digits/letters or more, or if it is more important than the corresponding description, for example, when no description is available, use a separate column for the item number.
  • If the item number is more like an ID in regards to its description, use ID formatting, like Description (ID).
For short numbers, add the item number to the description
For short numbers, add the item number to the description

Try not to display an empty responsive table. If there is no way around this, provide instructions on how to fill the table with data (sap.m.Table/ sap.m.ListBase, properties: showNoData, noDataText).

Remove the item count in the table title if there are zero items.

Provide meaningful instructions
Provide meaningful instructions

Item States

To show that an item is unread, use the corresponding flag (sap.m.Table, property: showUnread, sap.m.ColumnListItem/ sap.m.ListItemBase, property: unread). This shows most of the content in bold font.

An unread item
An unread item

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) at the bottom of the column that identifies the line item.

A modified item
A modified item

To show that a modified item has an error, for example, within the global edit flow, add the string (Contains errors) at the bottom of the column that identifies the line item. Use an object status control with the error state for it (sap.m.ObjectStatus, property: state, value: sap.ui.core.ValueState.Error).

A modified item with an error
A modified item with an error

To show that an item is locked, use a transparent-style button with the corresponding icon and the text Locked by [Name] at the bottom of the identifying column. The user can click or tap the button to open a quick view of the person.

A locked item
A locked item

To show that an item is in a draft state, use a transparent-style button with the text Draft at the bottom of the identifying column. The user can click or tap the button to open a popover showing the timestamp of the last change.

Item in draft state
Item in draft state

Show only one state at any one time.

Highlight Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to show:

  • A semantic state, such as red or orange for an error or warning.
  • A neutral highlight, such as blue to highlight newly added items.

(Property: highlight)

Highlighted items
Highlighted items

Numbers and Units

Show the unit of measurement together with the number within the item rows.

Do not put the unit in the column header. Do not use an additional column to show the unit of measurement. This is also valid for prices.

Unit of mesaurement – In line
Unit of mesaurement – In line

For numbers with units, show the correct formatting by using the object number control.

Object number
Object number

For the most important number with its unit, show the correct formatting by using the object number control and the emphasized flag.
Exception: If all numbers are of equal importance, emphasize none of them.

If the screen width is small, do not hide this column or move it to the pop-in area.
Exception: If the column containing the object identifier and the column containing the key attribute do not fit together on the screen, move the column containing the key attribute to the pop-in area.

Object number (emphasized)
Object number (emphasized)

Actions

To trigger actions on multiple items, use a multiselection table (sap.m.Table, property: mode, value: sap.m.ListMode.MultiSelect):

  • Offer the corresponding actions in the footer toolbar if the responsive table is the only area on the screen where actions can be applied. This has the advantage that the actions on the footer toolbar are fixed on the screen and you cannot scroll them away.
  • In all other cases, show the actions on the table toolbar.

Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.

To trigger actions on a single item only (sap.m.Table, property: mode, value: sap.m.ListMode.SingleSelectMaster):

  • Offer the corresponding actions in the footer toolbar if the responsive table is the only area on the screen to which actions can be applied. This has the advantage that the actions on the footer toolbar are fixed on the screen and cannot be scrolled away.
  • In other cases, show the actions on the table toolbar.
  • In rare cases, show the actions within the line item. Since these actions are repeated in every line and thus use a lot of screen real estate, only do this for one or two actions at most. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions, but instead use transparent-style buttons. An exception to this is if the action trigger belongs to a link.
Do: Place actions near to the objects to which they belong
Do: Place actions near to the objects to which they belong

The following actions on single items must always be in-line:

Delete: Use “Delete” table mode (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a Delete button at the end of each row.

Delete button
Delete button

Navigation: Use the “Navigation” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a Navigation indicator at the end of each row.

Use this to navigate to a new page containing line item details. In rare cases, you can also use this for navigation within the table without navigating to another page.

Navigation indicator
Navigation indicator

Edit: Use the “Detail” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an Edit icon at the end of each row.

Edit button
Edit button

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation.

Edit and navigation cannot be combined.

To trigger actions that are independent of the selection, show the actions on the table toolbar. Examples of such actions are add, edit (in the sense of changing the whole table to edit mode), sort, filter, group (or view settings), and table personalization.

To trigger a default action on the whole line item, use the “Active” or “DetailAndActive” column list item type (sap.m.ColumnListItem/ sap.m.ListItemBase, property: type, value: sap.m.ListType.Active).

Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Clicks on interactive controls within the item do not trigger the event, but are handled by the interactive control.

Do not use this for navigation, to switch the line item to an edit state, or to delete the item.

Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection.

Add Items

Place the Add button on the table toolbar. It can be displayed as an icon ( ) or text (for example, Add or Create).

In general, new items always appear as the first item of the table and contain a visual highlight at the beginning of the row.

After pressing the Add button, there are three possibilities for adding an item, which should be considered in the following priority:

  1. Add the item inline. Create an empty, editable row as the first item of the table. Show the Save button on the table toolbar. This option is recommended for simple scenarios with about ten columns.
  2. Open a dialog for larger tables with more than ten columns. Save the new item at the dialog level.
  3. Navigate to a new page. This behavior should only be used for very complex scenarios (for example, when a dialog cannot handle the amount of content anymore). After pressing the Save button in the footer toolbar on the create page, navigate back to the table.

There are three different states of a new item:

  1. New: The item was just created and is in edit mode. It is highlighted with a visual indicator.
  2. Recent: The item was saved, but is still highlighted and displayed as the first item of the table. Current filter, sort and group criteria are ignored since the item should remain visible.
  3. As soon as the responsive table is sorted, filtered, or grouped again, the new item is handled accordingly and looses the visual highlight, but not before.

In the context of the draft handling new items are not saved on table level, but rather with the entire draft.

Add button in table toolbar
Add button in table toolbar
New item as first row in edit mode
New item as first row in edit mode
Saved new item still with highlight and as first item
Saved new item still with highlight and as first item

Editable Content

For editable content, use input fields and any other interactive controls within the table cells that meet your input needs.

All SAPUI5 controls can be used.

If you need edit mode, change your text controls, such as label, text, and link, to input fields, or other appropriate controls as soon as you switch to edit mode, but not before.

You can do this by exchanging the control or, in more complex cases, by exchanging the entire responsive table.

For mass editing items:

  • Provide multiselection (sap.m.Table/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
  • Provide an Edit button.
  • If several items are selected, choosing the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

This is similar to mass editing in the split screen app.

View Settings: Sort, Filter, and Group

Sort, filter, and/or group settings are handled in the view settings dialog. This dialog can provide any combination of these three settings, including just one setting, such as sort only.

  • If sorting, filtering, and/or grouping are a common use case in your app, offer one, two, or all three of the corresponding features in one or more view settings dialogs. Note: Do not offer 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.

To trigger the view settings dialog, provide several buttons, one for each of these view settings. Each button opens a view settings dialog that contains only the relevant page.

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

Using the view settings dialog allows you to define several sort, filter, and/or group settings per column. Therefore, you can sort, filter, and/or group a column with several data points independently by each data point.

Several triggers for the different view settings (sort, filter, group)
Several triggers for the different view settings (sort, filter, group)

To display the current filter state, use the info bar below the table title. Clicking or tapping the info bar opens the view settings dialog on the filter page.

Show the info bar only if the filter settings are not shown somewhere else. For example, do not show the info bar for settings taken in the filter bar or in a select placed in the table toolbar.

If the info bar is shown, provide an option to reset all corresponding filters on the info bar.

Filtered table
Filtered table

To display the current group state, group headers are shown.

On the group header, show the following text (sap.m.GroupHeaderListItem, property: title):

[Label of the grouped column]: [Grouping Value]

Do not use several values on the group header.

Grouped table
Grouped table

Persist the view settings. When a user reopens the app, show the analytical table with the same sort, filter, and group settings as last defined by this user.

Personalization

To add, remove, or rearrange columns, use the table personalization dialog. Trigger the dialog via a button in 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 doing so, try to reduce the number of columns, for example, by using several lines per column or by utilizing the pop-in function. See the cheat sheet for an example.

View settings and table personalization icons
View settings and table personalization icons

Persist the column layout settings. When a user reopens the app, show the responsive table with the same column layout as last defined by this user.

Properties

sap.m.Table

The following additional properties are available for the responsive table:

  • The property: fixedLayout defines the algorithm the control uses to define column width. Setting it to “false” would perform automatic calculations for the column width, based on the longest non-breakable content. You should always set it to “true” for performance reasons. Exceptions are permissible if the table has only a few columns on a large screen width and fewer than 10 rows are displayed.
  • The property: backgroundDesign defines the background on which items are rendered. Use the default value.
  • The property: showOverlay provides an overlay on the whole table, which prevents use of the responsive table. This is used within the list report floorplan to mark the table as outdated after filter settings have been changed but the new filter settings have not yet been applied. Do not use it in other cases.
  • The property: insert adds a margin on all sides of the responsive table.
  • The property: headerText is a simple way to set the table title if you just need a title. However, do not use any of the following:
    • A separate toolbar
    • variantManagement
    • headerToolbar aggregation
  • The property: headerDesign affects the appearance of the header if the theme supports it. Leave the default value as it is.
  • The property: footerText adds a small additional row below the table footer or last item. This row can contain text only. Do not use this property.
  • The property: width defines the width of the whole table.
  • The property: includeItemInSelection uses a click on the whole line item to select the corresponding item if the responsive table is in a selection mode. This competes with other settings like “Navigation” or “Active” and should therefore not be used.
  • The property: enableBusyIndicator automatically shows a busy indicator while data is loaded. (In contrast to the property: busy, where the application can control when the table is set to busy state)
  • The property: modeAnimationOn does not have any effect. Do not use it.
  • The property: showSeparators allows you to show all, none, or some separators. The default setting, which is to show all separators, is to be used.
  • The property: swipeDirection allows you to define the direction in which to swipe if additional actions are hidden behind a table row. This works only on touch devices. Do not use this property.
  • The property: rememberSelections leaves items selected even if they are not currently visible, for example, through filtering. If this behavior is not wanted, set the flag to “false”, but you should do so only in exceptional cases.
  • The property: busy sets the table to a busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
  • The property: busyIndicatorDelay defines the time after which a busy state is shown after the responsive table has been set to this state. Use the default value.
  • The property: visible shows the table (“true”) or hides it (“false”).
  • The property: tooltip does not have an effect. Do not use it.

sap.m.Column

The following additional properties are available for sap.m.Column:

  • The property: width defines the width of the column in all units allowed by HTML, such as em, rem, %, and px.
  • The property: styleClass is used if you need to change the visual design of a column. Do not use this, but use the default style instead.
  • The property: visible shows or hides the column.
  • The property: tooltip does not have an effect. Do not use it.

sap.m.ColumnListItem

The following additional properties are available for sap.m.ColumnListItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: counter does not have any effect. Do not use it.
  • Do not use the property: busy.
  • Do not use the property: busyIndicatorDelay.
  • The property: visible shows or hides the item.
  • The property: tooltip adds a tooltip to a whole row. The tooltip is only shown on mouse interaction. It will not work on tablets or smartphones. Do not use it.

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

Implementation

Analytical Table (ALV)

An analytical table contains a set of data that is structured in rows and columns. It provides several powerful possibilities for working with the data, including advanced grouping and aggregations.

In contrast to other tables, the analytical data binding used by the analytical table allows an aggregated number to be shown automatically in a cell. This means that a number in such a summarized cell is a total sum of several lines in the database.

Usage

Use the analytical table (ALV) if:

  • The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You have to work on more than 1,000 rows. In this case, the analytical table is easier to handle. In contrast to the responsive table, the architecture of the analytical table is optimized for handling large numbers of items. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • Comparing items is a major use case. In this case, an analytical table might be more appropriate than a responsive table. In the analytical table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that an analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

Do not use the analytical table (ALV) if:

  • You need a table. The responsive tableis the default table in SAP Fiori. Additional use cases where you might need the responsive table include:
    • You need to provide a total sum for one column. You can also add totals to the responsive table.
    • The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices (such as purchase orders and purchase requisitions).
    • Selecting one or more items is a main use case and details are needed to choose the correct item.
    • Line items are independent of each other and no operation across columns is needed.
    • You want to have only one implementation for all devices.
  • The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
  • The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance. Examples include the master list and the attachment list.
  • You cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. Note that the grid table provides only one level of grouping, no aggregation options, and is also not responsive.
  • Data needs to be structured in a hierarchical manner. In this case, a tree table might be more appropriate. Although the analytical table can have several grouping levels, it is not as flexible when nodes at several levels contain children. Note that neither the tree table nor the analytical table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
  • You need an overview of a large amount of data. In this case, use charts.
  • You just need it for layout reasons. In this case, use a layout container like HBox or VBox.
  • You need read-only or editable field-value pairs. Use a form instead. The analytical table is not optimized for form-like input navigation.

Responsiveness

An analytical table is not responsive. It is available for desktops only and does not support touch devices.

If you use an analytical table for desktop use cases, note that you must implement a fallback solution for mobile and touch devices. This fallback solution does not need to support all use cases.

You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.

Analytical table (ALV) shown on a desktop
Analytical table (ALV) shown on a desktop
Analytical table (ALV) shown on a tablet
Analytical table (ALV) shown on a tablet

Components

An analytical table does not consist of other elements. However, it is common to use a toolbar above the analytical table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

An analytical table is quite restricted in terms of its content, although it provides powerful features for working with the content.

Table Level

Scroll

An analytical table allows horizontal and vertical scrolling (sap.ui.table.AnalyticalTable, property: navigationMode, value: Scrollbar).

You can add any number of line items to the analytical table, which is known as “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.AnalyticalTable, property: rowHeight).

Scroll bar
Scroll bar

Select

An analytical table can have one of the following selection types (sap.ui.table.AnalyticalTable/ property: selectionMode):

None: Items cannot be selected.

A non-selection analytical table
A non-selection analytical table

Single: One item in the analytical table can be selected. A row selector column is shown.

A single-selection analytical table
A single-selection analytical table
  • Multi Toggle: A multiselection mode that allows one or more items to be selected. For this, the grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back.
  • Select All: Works via a checkbox on the left of the column header (sap.ui.table.Table, property: enableSelectAll). Using the Select Allcheckbox selects or deselects all items the user can reach via scrolling. Use Select All only if it makes sense. Note that selecting a lot of data also takes time and might not be appropriate for all use cases. For example, a delete operation on two million database entries might not be very helpful in many cases.

You can also use the keyboard keys Shift and Ctrl for multiselection.

Avoid using checkboxes in the first column after the multiselect column of analytical tables with multiselection.

A multiselection analytical table
A multiselection analytical table
Don't
Do not add checkboxes to the first column
Do not add checkboxes to the first column

An item can be selected in different ways, depending on the configuration of the analytical table (sap.ui.table.AnalyticalTable, property: selectionBehavior):

  • Row: An item is selected by clicking the checkbox or the row. Use this for multiselection analytical tables if clicking a row is not used for something else.
  • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this if you need to click the row for something else, such as navigation.
  • RowOnly: An item is selected only by clicking the row, and not the checkboxes in the selector cells. Use this for single-selection analytical tables if clicking a row is not used for something else, such as navigation.

Compact, Cozy, and Condensed

Like all SAP Fiori controls, the analytical table is shown in compact mode on a desktop and in cozy mode on tablets.

For desktop devices, you can fit even more rows onto the screen by using the condensed mode together with the compact mode. This renders less white space for each item.

Note that the condensed content density must always be set in addition to the compact mode. Do not use the condensed mode on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable or unwanted results, such as cozy-sized controls in condensed-sized containers, missing padding, and so on.

Note that neither compact mode nor condensed mode support touch interaction. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells with their fingers.

For more information on cozy and compact modes, see content density.

 

 

 

 

 

Analytical table in compact mode
Analytical table in compact mode
Analytical table in condensed mode - more items on the same screen real estate
Analytical table in condensed mode - more items on the same screen real estate

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

  • Mouse interaction: The user drags the separator line between two columns (sap.ui.table.AnalyticalColumn, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.AnalyticalColumn, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
  • Touch interaction: The user clicks or taps the column header to reveal two buttons: one to show the column header menu and one for resizing. The user drags the latter to resize the column.

When the user resizes a column, the adaptation of the column width depends on how the column widths are set:

  • If column widths are set in pixel-based units (px, em, rem), the resized column is adapted and subsequent columns are moved accordingly. The width of all other columns is not affected.
    If all the columns together do not use up the full width of the table control, empty space is added. If all the columns together exceed the width of the table control, a scrollbar appears.
  • If all column widths are set as percentages or “auto”, resizing one column automatically resizes one or more other columns. Resizing can also affect the position of the resized column. This option utilizes the full width of the table and ensures that no white space is added. A scrollbar appears only if all or most of the columns become to narrow. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this minimum width is only taken into account if columns are resized automatically. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

Users can rearrange columns by dragging the column header to another position (sap.ui.table.AnalyticalTable, property: enableColumnReordering).

Column header
Column header
Opening the column header menu on touch devices
Opening the column header menu on touch devices
Columns do not use up the available space
Columns do not use up the available space

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.AnalyticalColumnMenu, property: Visible):

  • Sort Ascending/Descending (sap.ui.table.AnalyticalColumn, property: showSortMenuEntries)
  • Free text filter (sap.ui.table.AnalyticalColumn, property: showFilterMenuEntries)
  • Group
  • Totals
  • Freeze from the first to the last specified column (sap.ui.table.AnalyticalTable, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu
Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table.AnalyticalColumn, properties: sortProperty, showSortMenuEntry):

  • Sort Ascending
  • Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu
Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.AnalyticalColumn, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing ENTER when the focus is on the filter input field, the analytical table is filtered by the corresponding column and value (sap.ui.table.AnalyticalTable, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.AnalyticalColumn, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

  • If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
  • Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.
Free text filter in column header menu
Free text filter in column header menu

Group

The column header menu can provide the option to group by this column (sap.ui.table.AnalyticalColumn, property: sortProperty).

One group collects all items with the same value within the corresponding column.

Group setting in column header menu
Group setting in column header menu

If line items are grouped in a column, every group is provided with a collapsible or expandable group header (sap.ui.table.AnalyticalColumn, property: grouped). The header text consists of the column name and the value for the corresponding group (sap.ui.table.AnalyticalColumn, property: groupHeaderFormatter). Several grouping levels are possible.

The corresponding column can be hidden to avoid duplicates (sap.ui.table.AnalyticalColumn, property: showIfGrouped). Exercise caution when using this option since hiding the column changes the table layout and may lead to confusion.

Group headers and the corresponding columns are shown – The relevant data is duplicated
Group headers and the corresponding columns are shown – The relevant data is duplicated
Group headers shown, the corresponding column hidden – No duplicates
Group headers shown, the corresponding column hidden – No duplicates

Aggregation

The column header menu can provide the option to show or hide aggregation totals for this column.

Aggregation in column header menu
Aggregation in column header menu

Intermediate aggregations are shown at group level for the corresponding columns if the group contains more than one line item (sap.ui.table.AnalyticalColumn, property: summed).

Group total
Group total

The overall aggregation is shown at the bottom of the analytical table.

Overal aggregation
Overal aggregation

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.AnalyticalTable, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table.AnalyticalTable, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu
Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height.

(sap.ui.table.AnalyticalTable, property: rowHeight)

Line item
Line item

Cell Level

A cell provides one data point.

It can contain one of the following controls to display this data point:

While it is technically possible to also use other controls, doing so could lead to issues with alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

Cell
Cell

Cells can provide a context menu that allows the corresponding column to be filtered by the value provided by the specific cell (sap.ui.table.AnalyticalTable, property: enableCellFilter).

This menu is only shown on non-touch devices.

Cell context menu
Cell context menu

Guidelines

Data Density vs. Complexity

The analytical table can be used to display and work with large amounts of data. Unfortunately, the analytical table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. To make the data easier to read, you should instead try the following:

  • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

You implement the table title by using a title control in a toolbar.

Use a table title if the title of an analytical table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the analytical table, for example, if a pricing conditions analytical table is the only control placed on a tab labeled Pricing Conditions.

Use a table title if you need the table toolbar. To avoid repeating text, feel free to use generic text as a table title, such as Items.

If you use a table title, show either a title for the table, with or without variant management, or an item count in the following format:

Items (2,534).

You can combine an item count with variant management.

The count of items in the table title includes all the visible items that a user can reach by scrolling or expanding groups. Group headers are not included.

Remove the item count in the table title if there are zero items.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.AnalyticalTable, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Columns – Best Practices

Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

By default, the analytical table assigns the same width to each column. We recommend overwriting this default to provide optimal space for your content (sap.ui.table.AnalyticalColumn, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the size of the browser window results in a scrollbar. If the user resizes a column, and the total width of all columns exceeds the table width, a scrollbar appears. If the columns do not take up the full table width, white space appears to the right of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Reducing the size of the browser window truncates the texts. This ensures that the columns fill up all the available space. A scrollbar appears only if width of all the columns still exceeds the table width after the automatic width adjustments. To avoid the side effect of undersized columns, you can set a minimum width per column. However, this this minimum width is only taken into account if columns are automatically resized. End users can still reduce the column width to below the defined minimum (sap.ui.table.Column, properties: width, minWidth).

If you set the column width to “auto”, the behavior is the same as for “percentage”. However, unlike “percentage”, “auto” distributes the columns equally.

To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following in mind:

  • For tables with only 2 to 3 columns, use pixel-based units. This ensures that the values in the columns are not spread over the whole screen on wide screens, which improves the readability of the line items.
  • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel based units. This avoids unintended side effects when resizing columns.
  • For all other tables, use whatever fits your case better.

Be cautious when mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it can also cause even more side effects when resizing a column. If you are using percentage-based widths for one or more columns, consider not allowing end users to resize columns at all.

Optimize column width for its initial visible content, including the column header texts.

Maintain a constant column width and avoid automatically adjusting it based on content changes.

In the default delivery, the initial visible content should not be truncated
In the default delivery, the initial visible content should not be truncated

Column Headers – Best Practices

Provide a label for each column in the column header. In the default delivery, do not truncate the column header texts.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text
Left-alignment of text

Right-align: numbers, except IDs, to ensure comparability of numbers and amounts.

Right-alignment of numbers
Right-alignment of numbers

Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to decimal point
Alignment to decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates
Right-alignment of dates

In general, center one-word status information and icons.

If there is an icon + text or if the status has more than two words in english language, left align the complete status column.

Center-alignment of one-word texts
Center-alignment of one-word texts

Content Formatting

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link
Emphasized link

For strings with IDs, use one of the following:

  • Show the ID in brackets after the corresponding string. Use this format if sorting, grouping, or filtering is only needed on the string, but not on the ID.
  • Show the ID in a separate column. Use this format if sorting, grouping, or filtering on the string and the ID is needed.
Text and ID in one column – Sorting, filtering, and grouping only on the text
Text and ID in one column – Sorting, filtering, and grouping only on the text
Text and ID in two columns – Allows sorting, filtering, and grouping on both
Text and ID in two columns – Allows sorting, filtering, and grouping on both

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.AnalyticalColumn, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation.

Optimize column width for typical content, not all content
Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

For example, a financial table consists of several columns with summarized cells. A summarized cell shows the total sum of several database entries. Each sum should be a link to a report that shows details about which database entries produce the total sum. The line item identifier should also be a link that provides more detail about the line item itself. Use a standard or emphasized link for the item identifier, and subtle links for the summarized cells.

Emphasized links, links, subtle links, and text
Emphasized links, links, subtle links, and text

Missing Value

If there is no value for a cell, leave it blank. Do not display text as N/A.

Leave empty fields blank
Leave empty fields blank

Numbering Items

In terms of numbering items:

  • If the item number is more like an ID with regard to its description, use ID formatting as described above.
  • In all other cases, use a separate column for the item number.
Add a separate column for the item number
Add a separate column for the item number

Status

For status information, use semantic colors on the foreground elements.

For status information on text, use an object status.

Semantic colors on text
Semantic colors on text

Empty Tables

Avoid empty analytical tables. If necessary, provide instructions on how to fill the analytical table with data (sap.ui.table.AnalyticalTable, properties: noDataText, showNoData).

Remove the item count in the table title if there are zero items.

Provide meaningful instructions
Provide meaningful instructions

Invalid State

To show an invalid state of the analytical table within the list report floorplan, show an overlay on the analytical table and the corresponding toolbar (sap.ui.table.AnalyticalTable, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the analytical table has not yet been updated.

Analytical table with invalid data
Analytical table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string (Modified) in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item
A modified item

To show that a modified item has an error, for example, within the global edit flow, add the string (Contains errors) in the Editing Status column. This string replaces the (Modified) string.

A modified item with an error
A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item
A locked item

To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

Item in draft state
Item in draft state

Show only one state at a time.

Numbers and Units

Show the unit of measurement in one of the following ways:

The number and unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

Use a currency control to display the concatenated string.

Number and unit of measurement in one cell
Number and unit of measurement in one cell

The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

Number and unit of measurement in two columns
Number and unit of measurement in two columns

Do not put the unit of measurement in the column header.

Actions

Multiple Items

To trigger actions on multiple items, use a multiselection analytical table (sap.ui.table.AnalyticalTable, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the analytical table.

Single Item

To trigger actions on a single item (sap.ui.table.AnalyticalTable, property: selectionMode, value: Single):

  • Show the actions on the table toolbar.
  • In rare cases, show the actions within the line item. Since these actions are repeated on every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions. Use transparent-style buttons instead, except if the action trigger belongs to a link.

In contrast to the responsive table,  the analytical table does not support navigation by clicking or tapping a single line item. To achieve similar behavior, choose one of the following options:

  • Use a link for the attribute that identifies the row. Clicking this link triggers the navigation. Choose this solution over the other two options.
  • Provide a toolbar button that triggers the navigation on a selected line item. This button only works if just one item is selected.
  • If neither option is possible, add an additional column showing the navigation indicator (>) and no column header text at the end of the row. Provide click events on all cells that do not contain interactive content, including the cells in the column with the navigation indicators. Clicking or tapping such a cell triggers the navigation. Note that this solution is not ideal as users can show, hide, and rearrange this column.

Single Cell

For triggering actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

Place the add button on the table toolbar. It can be displayed as an icon ( ) or text (such as Add or Create).

New items always appear as the first item in the table.

For more details, please check the guidelines for managing objects (including subarticles).

Editable Content

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the analytical table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

  • Provide multiselection.
  • Provide an Edit button.
  • If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

This is similar to mass editing in the split-screen layout floorplan.

Interactive controls – In line
Interactive controls – In line
Warning
Do not offer editing for summarized cells. A summarized cell shows the total sum of several database entries. Changing the total sum does not make sense since it is unclear how this sum is divided between the different database entries.

View Settings

There are several ways to show Sort, Filter, and/or Group settings:

  • Column header menu: In all cases, show the corresponding settings in the column header menu.
  • View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
  • Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
  • If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

  • View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
  • Table personalization dialog: Provide a settings button, which opens the table personalization dialog containing all pages.

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

 

Persist the view settings. When a user reopens the app, show the analytical table with the same sort, filter, group, and aggregation settings as last defined by this user.

Column header menu with view settings
Column header menu with view settings
Table toolbar with triggers for view settings dialog
Table toolbar with triggers for view settings dialog
Table toolbar with trigger for table personalization dialog
Table toolbar with trigger for table personalization dialog

Sort

To display the current sort state, an icon is shown in the column header of the last sorted column. This icon indicates the sort direction (sap.ui.table.AnalyticalColumn, properties: sorted, sortOrder, sortProperty).

For the default sort setting, sort by the column that identifies the row, which is usually the first column in default delivery. Use a meaningful sort order, such as alphabetical order for text, numeric order for numbers, or chronological order for dates.

Column, sorted ascending
Column, sorted ascending
Column, sorted descending
Column, sorted descending

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.AnalyticalColumn, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered
Column, filtered

Group

To display the current group state, group headers are shown. Show the following text in the group header (sap.ui.table.AnalyticalColumn, properties: grouped, showIfGrouped, groupHeaderFormatter):

[Label of the grouped column]: [Grouping value]

Group headers, several levels
Group headers, several levels

On non-touch devices, right-clicking a group header opens the group header menu. On touch devices, the same menu is opened by using the menu icon on the right side of a group header.

The group header menu provides several options:

  • Show/Hide: Shows or hides the column in the table layout, although it is grouped.
  • Ungroup: When the user ungroups a column, the corresponding group headers disappear. If the column was hidden, it is shown again as a separate column.
  • Ungroup All: The columns are shown again.
  • Move Up: Rearranges the grouping levels hierarchy by moving the selected group above the group that is one level higher up in the hierarchy.
  • Move Down: Rearranges the grouping levels hierarchy by moving the selected group below the group that is one level lower down in the hierarchy.
  • Collapse Level: Collapses all groups on the corresponding grouping level.
  • Collapse All: All groups are collapsed.
Group header menu
Group header menu
Group header on touch devices
Group header on touch devices

In general:

  • Offer grouping on objects and attributes.
  • Do not offer grouping on measures.
  • If appropriate, offer reasonable grouping by default, but do not exaggerate. As a rule of thumb, use up to three group levels.
  • Provide more space for the first column. Grouping needs an indent per group level. Extra space in the first column prevents truncated text.

Aggregate

To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.

If items are grouped, an intermediate sum is shown:

  • At the bottom of each group if the group is expanded.
  • In the group header if the group is collapsed.

(sap.ui.table.AnalyticalColumn, property: summed)

For aggregating numbers with different units of measurements, show an asterisk (*) in the aggregation rows.

In general:

  • Offer aggregation on measures, but not on objects or attributes.
  • Avoid aggregations on the first three columns for the default delivery. As soon as grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.
  • Where appropriate, offer reasonable aggregation by default.
Aggregation and groups
Aggregation and groups

Personalization

Only offer personalization if you need more columns than a tablet screen can display at any one time, which is usually five.

Persist the column layout. When a user reopens the app, show the analytical table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

  • The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
  • The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

  • Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column for the data currently loaded into the front end, which is usually about 100 rows.
  • Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

For freezing columns, offer the setting in the column header menu (sap.ui.table.AnalyticalTable, property: enableColumnFreeze).

Selecting Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column
Frozen column

Properties

sap.ui.table.AnalyticalTable

The following additional properties are available for the analytical table:

  • The property: width defines the width of the analytical table.
  • The property: rowHeight defines the height of each row in the analytical table. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
  • The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the analytical table, this property is only needed rarely.
  • The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
  • The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
  • The property: columnVisibilityMenuSorter is used for sorting the columns inside the column header menu if showing and hiding columns is provided in the menu. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
  • The property: visibleRowCount defines the height of the analytical table. Show as many rows as fit on the screen.
  • The property: visibleRowCountMode defines whether the height of the analytical table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
  • The property: minimumAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
  • The property: firstVisibleRow defines the first row shown in the visible area of the analytical table. The analytical table is scrolled accordingly.
  • The property: allowColumnReordering is deprecated. Use the property: enableColumnReordering instead.
  • The property: editable does not have a visible effect. Please do not use it.
  • The property: threshold is used for optimizing lazy loading of items. In most cases, the default value is appropriate.
  • The property: enableGrouping is experimental and does not have a meaningful effect on the analytical table. Do not use it.
  • The property: sumOnTop shows additional aggregation values on the group header, even if the group is expanded. Do not use it.
  • The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event that apps can react to, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
  • The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
  • The property: title adds a line of text on top of the analytical table. Do not use it. To add a title to the table, use a toolbar.
  • The property: footer adds a short text at the bottom of the table.
  • The property: Busy sets the analytical table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
  • The property: Tooltip does not have an effect. Do not use it.

sap.ui.table.AnalyticalColumn

The following additional properties are available for the analytical column:

  • The property: leadingProperty is used for data binding.
  • The property: inResult is used for data binding.
  • The property: visible defines whether a column is shown or hidden.
  • The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Please do not use this property.
  • The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Please do not use this property.
  • The property: Tooltip does not have an effect. Please do not use it.

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

Implementation

Smart Link

Like the quick view, the smart link triggers a popover from a text link. This popover shows additional information, such as simple object details, and offers links to related apps for the user to take action. The user can choose which links are shown in the popover by selecting them in a separate dialog.
The smart link is a smart control that uses metadata annotations to offer user-specific navigation. It analyzes the user’s assigned apps and offers only relevant navigation targets.

Usage

Use the smart link to offer direct navigation to related apps. For example:

  • Navigate from a product list to the app to change the pricing
  • Navigate from a sales order list to the app to see a customer’s balance

Use the smart link if:

  • You want to offer related apps for navigation.
  • You want to display simple object details.

Do not use the smart link if:

  • You want to display more or complex information about an object. Use the object page or charts instead.
  • No metadata is accessible, and only a direct link to a website, document or application is needed. Use the standard link instead.
  • You need to structure information in a deeper hierarchy. Use the quick view or a list drilldown instead.

Responsiveness

The responsiveness of the smart link is based on the responsiveness of the popover and overlays the content.

On a desktop device, clicking anywhere in the background closes the popover.

On mobile devices, the smart link opens a dialog that overlays the entire content. Because the content underneath the popover is no longer directly visible to the end user, the dialog has a header and shows the object type. The dialog can be closed by clicking the close icon ( ) in the header.

Size S – On smartphones, the smart link overlays the content
Size S – On smartphones, the smart link overlays the content
Sizs M/ L - Smart link shown in a table on a desktop device
Sizs M/ L - Smart link shown in a table on a desktop device

Layout

The smart link contains the following areas:

  1. The header bar of the smart link popover indicates the type of object and is only shown on mobile devices.
  2. The title area contains a title and a subtitle. The title can also be shown as a link, which can be used to navigate to the corresponding object or fact sheet. The subtitle can be used to show the ID of the object, for example.
  3. The content area shows object-related information, such as details about a product or contact information. You can use any UI control, based on what best fits your use case.
  4. The link area offers links to all other apps that are relevant for a user role. The link list includes all semantic objects defined for the app, and can also include additional links defined manually by the application development team. The link area can have two states:

Link area is empty:
If no links have been selected for the app, or if there are more than 10 links, the link area is initially empty. Instead, the user sees a Define Links button, which opens a dialog for selecting the links to be shown.

Links are shown:
As soon the link area contains links, the button text changes to More. This opens the same selection dialog.

Only the header bar is mandatory (for mobile devices). All the other sections are optional. Depending on the use case, the application could offer only a content area, or a only a link area, for example.

The areas of the smart link (header bar not shown)
The areas of the smart link (header bar not shown)

Behavior and Interaction

The smart link and its popover are always triggered by clicking or tapping a text element that appears as a link. This text element can be placed in any list, table, or other container. The link label can be set individually. Clicking or tapping the background closes the popover. If only one link is offered, and there is no additional information, the smart link control navigates directly to the target without opening the popover.

If the semantic object annotation is not set, the smart link is rendered as sap.m.Text by default. However, app developers can also decide to render any other control.

Link Selection Dialog

Clicking the More or Define Links button opens the Define Link List dialog. There, the user can select the app links to be displayed in the link area. The links offered in the selection list are modifiable semantic objects suggested by the smart link control. Application development teams can remove links from the selection list and change the link texts. They can also manually add links to any website or app.

Exception: Within an SAP Fiori element, the links offered in the Define Link List dialog are generated automatically. Application teams cannot adapt the list.

You can switch off the More/Define Links option by setting the property enableAvailableActionsPersonalization to “false”. By default it is set to “true”.

Smart Links in a Smart Table

Within a smart table, the link label of the smart link is set automatically using the semantic object annotation. In other words, the description cannot be changed. If there are no navigation targets, the smart link is rendered as sap.m.Text.

Link selection dialog with a list of application links
Link selection dialog with a list of application links

Guidelines

  • Please check the related apps you offer carefully. Only display the ones that are relevant to the user.
  • Use meaningful link names in the link area. Do not use the same link name more than once. If necessary, rename the links to suit your context (for example, “Add Product” instead of “Manage Products”).

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

Implementation

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 L
Planning calendar - Size M
Planning calendar - Size M
Planning calendar - Size S
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 shown in single-select mode. 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
Switching to multi-select mode

Components

This section describes the various components of the planning calendar.

The control consists of different parts:

  1. Toolbar
  2. Header
  3. Calendar view
  4. List item
  5. Row header
  6. Row
  7. Appointment
  8. Interval appointment
Parts of the planning calendar
Parts of the planning calendar

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-sSelect 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 view (Hours, Days, or Months or Week) the appointments display and how many values are shown. 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.

Week view always displays seven days in one screen. It can be found in the view select as a default view. When applications have this view available, we strongly recommended 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 the two views differs.

The start date is always the beginning of the week. This can be Saturday, Sunday, or Monday, depending on the locale data.

Users can also navigate to the next or previous view, and easily switch to another year, month, or day.

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. This is useful if users want to view calendars from different countries that have different weekends.

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.

7. Appointment

Appointments enable an icon or picture, a title, and a subtitle to be shown. If appointments appear simultaneously, they are shown under each other.

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, and the app development team must define what happens next.

If the view changes and there are too many small appointments at one time, an aggregation is shown. Aggregations show a number indicating how many appointments are not fully visible in this view. This functionality will be improved in future releases. Otherwise, the click/touch area would be too small.

There are two sizes of appointments – regular and half size. The half-sized appointments can save space, but also note that they do not show a second line for details of the appointment.

8. Interval appointment

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

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 created 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, not truncated. However, this should not be an issue because the main use case is to see whether there is a free time slot. Additionally, the user can click or tap the appointment to see the details.

In the month view, appointments may appear as aggregations due to lack of space for detailed visualization. Aggregations show a number indicating how many appointments are not fully visible in this view.

The “alternating rows” functionality gives users the possibility to row coloring on or off. By default, the alternating rows option is turned on.

Appointments in the calendar have two sizes, regular and half appointment. The exact sizes can be found in the visual specification. The app developer can choose the size that fits the use case, but keep in mind that the half-size appointment shows less information about the appointment.

With “hiding the interval header”, the user also has the option to hide the interval header and the space that is reserved for it. This option can be included as an icon in the toolbar.

1. Switch

The switch is optional and allows users to switch between different views. For example, a user can get an overview of a whole year by selecting the year view. The average length of appointments and the use case should decide which view is the most useful.

2. Today action

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

3. Back and forward navigation

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

4. Day switch

The day switch is only available if the day view is selected. It enables the user to navigate to a different day.

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
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 current day to open the date picker. When the user selects a day, the picker closes and navigates the user to the selected value.
Navigation flow - Switching a day
Navigation flow - Switching a day

Guidelines

Switching the Row Header

If you want the end user to be able 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 should 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

Implementation

Dynamic Side Content

Dynamic side content is a layout control that displays additional content to help the user better understand the data that’s being displayed on the screen.  It is displayed in a way that flexibly adapts to different screen sizes.

App development teams can configure the behavior of the control on smaller screen sizes by following the relevant guidelines.

Dynamic side content layout
Dynamic side content layout

Usage

Use dynamic side content if:

  • You want to display information that:
    • Will enrich the main content and will help the user better perform his/her tasks;
    • Has meaning only when it is displayed next to the given container (side-by-side, below or on top of it);
    • Influences the main content (for example, a filter for list; settings for chart, details for map).
  • Users should have access to all of the key functions and critical information in the app even if they do not see the side content. This is important because on smaller screen sizes it may be difficult to display the side content in a way that is easily accessible for the user.

Do not use dynamic side content if:

  • You want to display critical information that should be visible all the time. The dynamic side content is not meant to split the page into two equally important sections.

  • You want to display navigation or drilldown.

Layout

Dynamic side content is displayed next to (left or right), on top of, or below a container that consists of the main information to which it is directly related.

The dynamic side content can be closed by a button that is displayed in its toolbar.

The dynamic side content can be opened, if it set to hidden, with an action within the container to which it is directly related, or by an action displayed in the container-related toolbar, if it is available.

When the dynamic side content is displayed side-by-side to the container, it doesn’t overlay it. The main container narrows down and makes space for the additional content to be displayed.

  • Dynamic side content positioning
  • Dynamic side content positioning
  • Dynamic side content positioning
  • Dynamic side content positioning

Responsiveness

The dynamic side content control is built for different screen sizes and layouts.

Different sizes of dynamic side content

  • Dynamic side content - Size S
  • Dynamic side content - Size M
  • Dynamic side content - Size L

The default screen layout features the side content on the left or right side of the screen, covering 25% of the screen width on a large desktop (over 1440 px).

Dynamic side content - Default layout
Dynamic side content - Default layout

On smaller screen sizes (under 1440 px), the side content occupies 33% of the screen width to accommodate the nested controls. If the side content width falls below 320 px, the side content automatically slides under the main content, unless the app development team specifies that it should disappear.

Dynamic side content - smaller screen sizes
Dynamic side content - smaller screen sizes

On screen sizes of less than or equal to 720 px, the side content automatically disappears from the screen (unless specified to stay under the content) and can be triggered from a preset trigger (specified within the app). When the side content is triggered, it replaces the main content. We recommend that you always place the trigger for the side content in the same location, such as in the container toolbar.

Equal split: A special view of the side content is the 50:50 view, which enables users to show more data, for example, for comparison purposes. The responsive behavior of the equal split is the same as in the standard view: The side content disappears on screen widths of less than 720 px and can only be viewed by triggering it.

Dynamic side content - Equal split
Dynamic side content - Equal split

The app development team may specify that the side content should slide under the main content when the screen is resized to a smaller width. Sliding the side content under the main content on smaller screens allows it to remain on the screen at all times. However, it may only be accessible via scrolling.

Guidelines

Dynamic Side Content in Object Page

Dynamic side content can be used within the object page. Use dynamic side content within a section if you want to give the user additional data related to this section. If you want to display additional information about the object such as a timeline, include this information as a new section.

Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page
Do
Correct usage of dynamic side content in object page
Correct usage of dynamic side content in object page
Don't
Wrong usage of the dynamic side content in object page
Wrong usage of the dynamic side content in object page

Do not separate the screen into two panels. Do not use it for navigation, for drilldown, or to show information that related to the entire object.

Dynamic Side Content in Dynamic Page

Do not separate the page into two panels when you are using it inside the dynamic page. The dynamic side content should be placed directly next to the page container and under the header container. The header snaps manually and the both sections have their own scrollbars.

Do
Correct usage of dynamic side content in dynamic page
Correct usage of dynamic side content in dynamic page
Don't
Wrong usage of the dynamic side content in dynamic page
Wrong usage of the dynamic side content in dynamic page

Examples

Dynamic side content in object page, used with map
Dynamic side content in object page, used with map
Dynamic side content in object page, used with planning calendar
Dynamic side content in object page, used with planning calendar
Dynamic side content with event list
Dynamic side content with event list

Use of Controls in the Dynamic Side Content

You can use most of the main controls in the dynamic side content, such as text, simple form, chart, list, panel, tree, timeline, or feed and notes. However, you must make sure that the control doesn’t result in the appearance of a horizontal scrollbar.

Do not use complex controls, such as tables.

Navigation

The side content is always related to the main content, so it must show content that can be triggered from the main content. This also means minimizing navigation, such as drill-ins within the side content, and displaying content that is triggered from the main content area. An example would be showing additional details such as contact information or conversation history. If a different type of data relates to the main content, app developers can implement a switcher in the side content. However, we recommend that you keep the side content free of additional navigation elements.

Triggering the side content

The side content can be set to hidden by default, and it automatically disappears when the screen width is less than or equal to 720 px (except when it is set to be under the main content).The app design team can define the trigger point. Our recommendation is to put a transparent text button with a meaningful label in the container toolbar, or an action inside the container the dynamic side content is related to. Ensure that the user can understand how to trigger the side content. Please, avoid using icons, because they can confuse the user.

Hiding the side content

The side content should be hidden from the header (top) section of the side content. The side content container itself has no header. We therefore strongly recommend that you use a toolbar control with a title, a transparent button labeled Close, and a spacer between them.

Hiding side content – From the header section
Hiding side content – From the header section

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

Implementation

Chart – Embedding

This article explains how to embed an SAP Fiori chart in an app in such a way that it has the correct size and scrolling behavior.

Developer Hint
The ChartContainer toolbar and FixFlex SAPUI5 control help you support these guidelines. See the “Resources” section at the end of this page.

Page vs. Frame

The optimal way to embed a chart component in an app depends on the layout pattern of the app. Embedding a chart component in a split-screen layout is different from embedding one in a full screen layout. Two main layout patterns must be considered: vertically-scrolled page and frame.

Vertically Scrolling Page

In this layout pattern, the page scrolls vertically. If the page content cannot be seen in full, a vertical scrollbar appears.

 

Layout examples:

Split-screen layout with object below the chart:

Chart embedded in a detail view
Chart embedded in a detail view

Object page or dashboard:

Chart embedded in an object page or dashboard
Chart embedded in an object page or dashboard

Full-width page:

Chart embedded in a full-width page
Chart embedded in a full-width page

Frame

In this layout pattern, the page contains multiple frames and does not scroll horizontally or vertically. If the page content cannot be seen in full, the frames are resized so that they remain visible. Some frames may remain with a fixed size, while other frames are resized. When a chart is embedded in a frame, the frame is generally resized.

 

Layout examples:

Split-screen layout with the chart as the last object in the detail view:

Chart embedded in a detail view
Chart embedded in a detail view

SAP Smart Business apps, full-screen app, analysis floorplan, list report floorplan:

Chart embedded in a frame
Chart embedded in a frame

Apps with multiple frames:

Two charts embedded in two frames
Two charts embedded in two frames

Embedding in a Page

How you embed a chart component in a vertically-scrolled page depends on its scrolling direction. Embedding a chart that scrolls horizontally is different from embedding one that scrolls vertically.

Horizontally Scrolling Charts

Charts that scroll horizontally are charts that might contain a horizontal scrollbar when the width of the chart cannot display the entire set of values. Typical examples are the line chart or column chart.

When a chart that scrolls horizontally is embedded in a page, the height of the chart component must be defined by the app developer and remains fixed, even when the height of the page changes. That means we can have together the vertical scrollbar of the page and the horizontal scrollbar of the chart control.

Height of a horizontally scrolled chart
Height of a horizontally scrolled chart

Vertically Scrolling Charts

Charts that scroll vertically are charts that might have a vertical scrollbar when the height of the chart cannot display the entire set of values. Typical examples are bar chart or stacked bars.

When a chart that scrolls vertically is embedded in a page, avoid having together the vertical scrollbar of the page and the vertical scrollbar of the chart control. A good way to avoid the vertical scrollbar within the chart is to choose a height for the chart component relatively big to see all data points or to set a specific zoom in order to see all data point (use window.start and window.end properties).

Height of a vertically scrolled chart
Height of a vertically scrolled chart

Charts Scrolling in Both Directions

Charts that have no main scrolling direction should be managed on a case-by-case basis.

Embedding in a Frame

In this layout pattern, the screen contains multiple frames and does not scroll horizontally or vertically. The scrolling is instead managed by each of the frames. When the chart component is embedded in a frame, it is resized to occupy the full height and width of the frame.

The chart component manages the scrollbars as necessary and displays the appropriate data point correctly.

Charts embedded in a frame
Charts embedded in a frame

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

Implementation

Grid Table

A grid table contains a set of data that is structured in rows and columns. It allows the user to scroll in both directions and can handle large numbers of items and columns.

Usage

Use the grid table if:

  • The cell level and the spatial relationship between cells are more important than the line item. Examples include spreadsheet analyses and waterfall charts. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You have to work on more than 1,000 rows. In this case, the grid table is easier to handle. In contrast to the responsive table, the architecture of the grid table is optimized for handling large numbers of items. Note that a grid table is not fully responsive. It is only available for desktop and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • Comparing items is a major use case. In this case, a grid table might be more appropriate than a responsive table. In the grid table, each cell contains only one data point. In contrast, the responsive table is more flexible regarding line items, including the ability to add more data points per cell and also the pop-in function. Both make comparisons more difficult. Note that a grid table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You need an analytical table, but you cannot provide an analytical binding on the technical side. In this case, a grid table will do the work. Note that the grid table provides only one level of grouping, no aggregation options, and is also not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.

Do not use the grid table if:

  • You need a table. The responsive table is the default table in SAP Fiori. Additional use cases where you might need the responsive table include:
    • The focus is on working on line items, not on cells. The responsive table is optimized for displaying complete items on all devices, such as file browsing and a list of documents you want to act on, like purchase orders and purchase requisitions.
    • Selecting one or several items is the main use case and details are needed to choose the correct item.
    • Line items are independent of each other and no operation across columns is needed.
    • You want to have only one implementation for all devices.
  • The main use case is choosing one item from a very small number of items with no additional details. A select or combo box might be more appropriate.
  • The main use case is choosing one out of several items with only a few details per item. A list might be more appropriate. Pay attention to the layout of the list item to ensure that it has a pleasant appearance. Examples include the master list and the attachment list.
  • Data needs to be structured in a hierarchical manner. Use a tree table instead. Note that neither the tree table nor the grid table are responsive. You will need to take an adaptive approach by offering an additional UI for smartphones and tablets.
  • You need an overview of a large amount of data. In this case, use charts.
  • You just need it for layout reasons. In this case, use a layout container such as HBox or VBox.
  • You need read-only or editable field-value pairs. Use a form instead. The grid table is not optimized for form-like input navigation.

Responsiveness

A grid table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

If you use a grid table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

You could create a fallback by using a responsive table, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

Grid table shown on a desktop
Grid table shown on a desktop
Grid table shown on a tablet
Grid table shown on a tablet

Layout

The column header allows the user to resize and rearrange columns. It also provides access to a menu with column-specific commands.

The collection of items, or rows, occupies the main part of the grid table.

The selector cells allow the user to select one or more items.

The Select All button selects or deselects all items.

Schematic visualization of the grid table
Schematic visualization of the grid table

Components

A grid table does not consist of other elements. However, it is common to use a toolbar above the grid table.

The toolbar can contain entry points for the view settings dialog and the table personalization dialog or for the p13n dialog, as well as view switches in the form of a segmented button, and buttons for Add, Edit, and other actions.

Behavior and Interaction

A grid table is quite restricted in terms of its content.

Table Level

Scroll

A grid table allows horizontal and vertical scrolling (sap.ui.table.Table, property: navigationMode, value: Scrollbar).

You can add any number of line items to the grid table, which is known as “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

Scroll bar
Scroll bar

Select

A grid table can have one of the following selection types (sap.ui.table.Table/ property: selectionMode):

  • None: Items cannot be selected.
A non-selection grid table
A non-selection grid table
  • Single: One item in the grid table can be selected. A row selector column is shown.
A single-selection grid table
A single-selection grid table
  • Multi Toggle: A multiselection mode that allows one or more items to be selected. For this, the grid table provides a column with checkboxes on the left-hand side. Clicking a checkbox toggles the state of the corresponding row from deselected to selected and back.
  • Select All: Works via a checkbox on the left of the column header (sap.ui.table.Table, property: enableSelectAll). Using the Select All checkbox selects or deselects all items the user can reach via scrolling. Use Select All only if it makes sense. Note that selecting a lot of data also takes time and might not be appropriate for all use cases. For example, a delete operation on two million database entries might not be very helpful in many cases.

You can also use the keyboard keys Shift and Ctrl for multiselection.

Avoid having checkboxes in the first column after the multiselect column of multiselection grid tables.

A multiselection grid table
A multiselection grid table
Do not add checkboxes to the first column
Do not add checkboxes to the first column

An item can be selected in different ways, depending on the configuration of the grid table (sap.ui.table.Table, property: selectionBehavior):

  • Row: An item is selected by clicking the checkbox or the row. Use this for multiselection grid tables if clicking a row is not used for something else.
  • RowSelector: An item is selected only by clicking the checkbox in the selector cell. Use this if you need to click the row for something else, such as navigation.
  • RowOnly: An item is selected only by clicking the row, and not the the checkboxes in the selector cells. Use this for single-selection grid tables if clicking a row is not used for something else, such as navigation.

Compact, Cozy, and Condensed

Like all SAP Fiori controls, the grid table is shown in compact mode on a desktop and in cozy mode on tablets.

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing padings, etc.

Note that neither compact mode nor condensed mode can be interacted with via touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

For more information on cozy and compact modes, see content density.

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Columns are resized as follows:

  • Mouse interaction: The user drags the separator line between two columns (sap.ui.table.Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
  • Touch interaction: The user clicks or taps the column header to reveal two buttons – one to show the column header menu, and one for resizing. The user drags the latter to resize the column.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

  • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and the columns that follow are moved accordingly. The width of all other columns is not affected.
    If all the columns together take up less width than the table control, an empty space is added. In case all columns together take up more width than the table control, a scrollbar appears. (sap.ui.table.Column, property: width)
  • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only if all or most of the columns shrink significantly. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.Table, property: enableColumnReordering).

Column header
Column header
Opening the column header menu on touch devices
Opening the column header menu on touch devices
Less columns than space available
Less columns than space available

Column Header Menu

For each column, a menu can contain the following menu items (sap.ui.table.ColumnMenu, property: visible):

  • Sort Ascending/Descending (sap.ui.table.Column, property: showSortMenuEntries)
  • Free text filter (sap.ui.table.Column, property: showFilterMenuEntries)
  • Group (sap.ui.table.Table, property: enableGrouping)
  • Freeze from the first to the last specified column (sap.ui.table.Table, property: enableColumnFreeze)

For each column, the menu can be replaced by an app-specific menu.

Column header menu
Column header menu

Sort

The column header menu can provide two sort options (sap.ui.table. Column, properties: sortProperty, showSortMenuEntry):

  • Sort Ascending
  • Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table. Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu
Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text (sap.ui.table.Column, properties: filterProperty, showFilterMenuEntries).

If the user enters a term in the input field and triggers the search by pressing Enter when the focus is on the filter input field, the grid table is filtered by the corresponding column and value (sap.ui.table.Table, properties: filtered, filterProperty, filterValue, filterOperator, sap.ui.table.Column, property: filterType).

Note that the filter may return zero results, in which case, the table might be empty.

General recommendations for filtering:

  • If filtering is a main use case, choose the filter bar or any other filtering UI over the built-in free text filter.
  • Only use the free text filter if filtering is a secondary use case and if the filter bar is too heavy.
Free text filter in column header menu
Free text filter in column header menu

Group

The column header menu can provide the option to group by this column (sap.ui.table.Column, property: enableGrouping).

One group collects all items with the same value within the corresponding column.

Group setting in column header menu
Group setting in column header menu

If line items are grouped in a column, every group is provided with a collapsible or expandable group header. The header text consists of the name of the value and the number of items in the specific group. Only one grouping level is possible.

Group header
Group header

Once line items have been grouped, the corresponding column is hidden. There is no built-in possibility to ungroup the grid table again. Therefore, provide a view settings dialog or table presonalization dialog to offer an additional way to group by a column and a way to ungroup the complete table.

An exception to this is when the table is grouped from the start and should not be ungrouped at all.

Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
Group headers shown, the corresponding column hidden: no duplicates, but a confusing change
Warning
Note that grouping the grid table is experimental and currently works only on items loaded to the front end. Thus, scrolling down the table leads to data not being grouped as expected.

Only use this feature if you have just a few line items, all of which are loaded to the front end. If this is the case, consider using a responsive table first instead of a grid table.

Freeze Columns

The column header menu can provide the option to freeze columns (sap.ui.table.Table, property: enableColumnFreeze). Selecting Freeze freezes all columns up to the one in which the operation was triggered (sap.ui.table. Table, property: fixedColumnCount).

When Freeze is triggered, the menu item changes to Unfreeze for the corresponding column.

Freeze setting in column header menu
Freeze setting in column header menu

Line Item Level

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.Table, property: rowHeight).

Line item
Line item

Cell Level

A cell provides one data point.

It can contain one of the following controls to display this data point:

While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

Cell
Cell

Cells can provide a context menu that allows the corresponding column to be filtered by the value provided by the specific cell (sap.ui.table.Table, property: enableCellFilter).

This menu is only shown on non-touch devices.

Cell context menu
Cell context menu

Guidelines

Data Density vs. Complexity

The grid table can be used to display large amounts of data. Unfortunately, the grid table has a high data density and therefore conveys an immediate feeling of complexity.

Only show tables with a lot of data as a last resort. Try the following instead:

  • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Try to minimize the number of columns, especially if there is a large number of rows.

Table Title

You can implement the table title by using a title control in a toolbar.

Use a table title if the title of a grid table is not indicated in the surrounding area. Do not use a table title if it simply repeats text that is already above the grid table, for example, if a pricing conditions grid table is the only control placed on a tab labeled Pricing Conditions.

Use a table title if you need the table toolbar. To avoid repeating text, feel free to use generic text as a table title, such as Items.

You can add an item count to the table title. If you do so, use the following format:

Items (345)

Text as well as text and an item count can both be combined with variant management.

The count of items in the table title displays all visible items which the user can reach via scrolling or expanding groups. Group headers do not count in.

Remove the item count in the table title if there are zero items.

Loading Data

To indicate that the table is currently loading items, use the busy state. (sap.ui.table.Table, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Grid table in busy state while loading data
Grid table in busy state while loading data

Columns – Best Practices

Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery.

The grid table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scroll bar appears if the width of the table is not enough to show all columns. If the columns use less space than available, white space appears on the right side of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough for showing all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum.

If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

To decide on how to set the column width (pixel / rem / em vs. percent / auto), keep the following in mind:

  • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves the readability of line items.
  • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
  • For all other tables, use whatever fits your case better.

Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unexpected side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

Optimize column width for its initial visible content, including the column header texts.

Maintain a constant column width and avoid automatically adjusting it based on content changes.

Don't: In the default delivery, the initial visible content should not be truncated
Don't: In the default delivery, the initial visible content should not be truncated

Column Headers – Best Practices

Provide a label for each column in the column header. In the default delivery, do not truncate the column header texts.

Content Alignment

For alignment of cell content, follow the guidelines below.

Left-align the following: text, IDs, phone numbers, URLs, passwords, and email addresses.

Left-alignment of text
Left-alignment of text

Right-align numbers (except IDs).

This ensures comparability of numbers and amounts.

Right-alignment of numbers
Right-alignment of numbers

Right-align amounts with currencies to the cell and align them in terms of their respective decimal points.

This ensures that amounts with different currencies are shown correctly, whether these currencies have 0, 2, or 3 decimals.

For aligning to the decimal point, use the sap.ui.uinified.Currency control.

Alignment to decimal point
Alignment to decimal point

Right-align dates and times.

This ensures comparability for most formats and locales.

Right-alignment of dates
Right-alignment of dates

In general, center one-word status information and icons.

If there is an icon and text, or if the status contains more than two words in the English language, left-align the entire status column.

Center-alignment of one-word texts
Center-alignment of one-word texts

Content Formatting

Locale Settings

Be locale-aware: show dates, times, numbers, and so on in the format corresponding to the user’s locale settings.

Key Identifier

Use a bold label or an emphasized link as the key identifier of an item. In the default delivery, show the key identifier in the first column.

Emphasized link
Emphasized link

For strings with IDs, use one of the following:

  • Show the ID in brackets after the corresponding string. Use this formatting if sorting, grouping, or filtering is only needed on the string, but not on the ID.
  • Show the ID in a separate column. Use this format if sorting, grouping, or filtering on the string and the ID is needed.
Text and ID in one column – Sorting, filtering, and grouping only on the text
Text and ID in one column – Sorting, filtering, and grouping only on the text
Text and ID in two columns – Allows sorting, filtering, and grouping on both
Text and ID in two columns – Allows sorting, filtering, and grouping on both

Truncation

Avoid truncation of typical content in the default delivery (sap.ui.table.Column, property: width). However, since the columns are resizable, do not worry too much if truncation occurs as columns can still be enlarged if necessary.

To prevent adverse side effects when scrolling vertically, all line items must also have the same height. If you need to decide between truncation and different row heights, choose truncation.

Optimize column width for typical content, not all content
Optimize column width for typical content, not all content

Number of Links

Are there too many links? Use subtle links to avoid a wall of links. Standard links are also emphasized more if they are surrounded by subtle links.

Emphasized links, links, subtle links, and text
Emphasized links, links, subtle links, and text

Missing Value

If there is no value for a cell, leave it blank. Do not display text as N/A.

Leave empty fields blank
Leave empty fields blank

Numbering Items

In terms of numbering items:

  • If the item number is more like an ID with regard to its description, use ID formatting as described above.
  • In all other cases, use a separate column for the item number.
Add a separate column for the item number
Add a separate column for the item number

Status

For status information, use semantic colors on the foreground elements.

For status information on text, use an object status.

Semantic colors on text
Semantic colors on text

Empty Tables

Avoid empty grid tables. If necessary, provide instructions on how to fill the grid table with data (sap.ui.table.Table, properties: noDataText, showNoData).

Remove the item count in the table title if there are zero items.

Provide meaningful instructions
Provide meaningful instructions

Invalid State

To show an invalid state of the grid table within the list report floorplan, show an overlay on the grid table and the corresponding toolbar (sap.ui.table.Table, property: showOverlay). The overlay prevents user interactions.

Use this within the list report floorplan if filter settings have been changed but the grid table is has not yet been updated.

Grid table with invalid data
Grid table with invalid data

Item States

To show that an item has been modified, for example, within the global edit flow, add the string Modified in an additional column with the label Editing Status.

In the default delivery, add a column directly behind the key identifier.

A modified item
A modified item

To show that a modified item has an error, for example, within the global edit flow, add the string Contains errors in the Editing Status column. This string replaces the Modified string.

A modified item with an error
A modified item with an error

To show that an item is locked, add a transparent-style button with the corresponding icon and the text Locked by [name] in the Editing Status column.

A locked item
A locked item

To show that an item is in draft state, add a transparent-style button with the text Draft in the Editing Status column.

Item in draft state
Item in draft state

Show only one state at a time.

Numbers and Units

Show the unit of measurement in one of the following ways:

Number and Unit in Same Cell

The number and the unit are in the same cell. Do this if sorting, filtering, or grouping by the unit of measurement are not needed.

Use a currency control to display the concatenated string.

Number and unit of measurement in one cell
Number and unit of measurement in one cell

Number and Unit in Separate Columns

The number and unit are in separate columns. Do this if sorting, filtering, or grouping by the unit of measurement are a common use case.

Note that this column can be hidden or moved independently of the column containing the corresponding number. Therefore, be sure to have clear labels for both columns to communicate the dependency.

Number and unit of measurement in two columns
Number and unit of measurement in two columns

Do not put the unit of measurement in the column header.

Actions

Multiple Items

To trigger actions on multiple items, use a mutliselection grid table (sap.ui.table.Table, property: selectionMode, value: MultiToggle). Offer the corresponding actions in the table toolbar.

Do not offer action triggering on multiple items if the table is generally expected to have fewer than 10 items. In this case, try to use the responsive table instead of the grid table.

Single Item

To trigger actions on a single item (sap.ui.table. Table, property: selectionMode, value: Single):

  • Show the actions on the table toolbar.
  • In rare cases, show the actions within the line item. Since these actions are repeated in every line and thus use a lot of screen real estate, do this only for a maximum of one or two actions. In this case, show the action trigger near the content to which it belongs. Do not add a specific column for actions. Use transparent-style buttons instead, except if the action trigger belongs to a link.

In contrast to the responsive table,  the grid table does not support navigation by clicking or tapping a single line item. To achieve similar behavior, choose one of the following options:

  • Use a link for the attribute that identifies the row. Clicking this link triggers the navigation. Choose this solution over the other two options.
  • Provide a toolbar button that triggers the navigation on a selected line item. This button only works if just one item is selected.
  • If neither option is possible, add an additional column showing the navigation indicator (>) and no column header text at the end of the row. Provide click events on all cells that do not contain interactive content, including the cells in the column with the navigation indicators. Clicking or tapping such a cell triggers the navigation. Note that this solution is not ideal as users can show, hide, and rearrange this column.

Single Cell

To trigger actions on a single cell, create the corresponding click event. Do not use the cell click event if the cell contains interactive controls, such as links.

Add Items

Place the add button on the table toolbar. It can be displayed as an icon (+) or text (e.g. ‘Add’ or ‘Create’).

In general new items always appear as the first item of the table.

Editable Content

For editable content, only use the following controls, and only one control per cell:

Only these controls are optimized for all viewing modes of the grid table.

If you need edit mode, change your text controls, such as label, text, link, object status, icons, and currencies, to editable controls as soon as you switch to edit mode, but not before. You can do this by exchanging the controls, for example, from sap.m.Text to sap.m.Input.

For mass editing items:

  • Provide multiselection.
  • Provide an Edit button.
  • If several items are selected, clicking the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

This is similar to mass editing in the split-screen layout floorplan. For more information, see editing multiple items in the master list article.

Interactive controls – In line
Interactive controls – In line

View Settings

There are several ways to show Sort, Filter, and/or Group settings:

  • Column header menu: In all cases, show the corresponding settings in the column header menu.
  • View settings dialog: Simple and more flexible with regard to filter settings. No advantage for sorting. Allows the user to ungroup grouped columns.tables with a medium amount of items.
  • Table personalization dialog: Provides complex options for sorting items by several levels and allows the user to ungroup grouped columns. It also provides a query-builder-like approach for filter settings. The complexity of the options is also its downside. Use the table personalization dialog for tables with a large number of items.
  • If filtering is a main use case, use the filter bar. In this case, avoid offering additional filter settings on the table. If you do, the filter settings on the grid table work only on the result set provided by the filter bar.

Always be careful when synchronizing the settings in the dialog with the settings from the column header menu.

Trigger the dialogs in one of the following ways:

  • View settings dialog: Provide several buttons, one for each of these view settings. Each button opens the view settings dialog on the corresponding page.
  • Table personalization dialog: Provide a settings button, which opens the table personalization dialog containing all pages.

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

Be persistent. When reopening the app, show the analytical table in the same view settings (sort/ filter/ group/ aggregation settings) as last defined by this user.

Column header menu with view settings
Column header menu with view settings
Table toolbar with triggers for view settings dialog
Table toolbar with triggers for view settings dialog
Table toolbar with trigger for table personalization dialog
Table toolbar with trigger for table personalization dialog

Sort

To display the current sort state, an icon is shown in the column header of the last sorted column. This icon indicates the sort direction (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

For the default sort settings, sort by the column that identifies the row, which is usually the first column in default delivery. Use a meaningful sort order, such as an alphabetical order for text, a numeric order for numbers, or a chronological order for dates.

Column, sorted ascending
Column, sorted ascending
Column, sorted descending
Column, sorted descending

Filter

To display the current filter state, an icon is shown in the column header of the filtered column (sap.ui.table.Column, properties: filtered, filterProperty, filterValue, filterOperator, defaultFilterOperator, filterType).

Column, filtered
Column, filtered

Group

To display the current group state, group headers are shown. Show the following text in the group header:

[Grouping value] – [Item count for the group]

Group headers
Group headers

In general, offer reasonable grouping by default if appropriate. Enable the user to ungroup via the view settings dialog or via the table personalization dialog.

Personalization

Only 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.

Persist the column layout. When a user reopens the app, show the grid table with the same column layout settings as last defined by this user.

Add, Remove, and Rearrange Columns

To add, remove, or rearrange columns, use one of the following:

  • The table personalization dialog: It offers some simple settings for column layout. Use this if you have only a few columns to choose from and/or you use the view settings dialog.
  • The p13n dialog: Besides various complex view settings, it also provides settings for column layout. Use this if you have a large number of columns to choose from and/or you use this dialog anyway for view settings.

In both cases, trigger the dialog via the settings button in the table toolbar.

You can also use drag and drop to rearrange columns (sap.ui.table.Table, property: enableColumnReordering). If you allow rearranging via drag and drop as well as via a dialog, keep both places in sync.

Resize Columns

Resizing columns works differently on touch and non-touch devices.

  • Non-touch devices: Drag and drop the column separator on the right side of the column. Double-clicking the column separator optimizes the width of the column to the data currently loaded into the front end, which is usually about 100 rows.
  • Touch devices: Clicking the column header reveals two buttons: one for opening the column header menu, another one for resizing the column. Drag and drop this second button to resize the column.

Freeze Columns

To freeze columns, offer the setting in the column header menu (sap.ui.table.Table, property: enableColumnFreeze). Selecing Freeze on a column freezes all columns from the first one to the one where Freeze is selected. On this column, the menu entry changes from Freeze to Unfreeze.

Frozen column
Frozen column

Properties

sap.ui.table.Table

The following additional properties are available for the grid table:

  • The property: width defines the width of the grid table.
  • The property: rowHeight defines the height of each row in the grid table. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
  • The property: columnHeaderHeight defines the height of the column headers. Since the height required is calculated automatically by the grid table, this property is only needed rarely.
  • The property: columnHeaderVisible can be used to hide the column headers. Always show the column headers.
  • The property: showColumnVisibilityMenu provides an additional entry in the column header menu that allows columns to be shown or hidden. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
  • The property: visibleRowCount defines the height of the grid table. Show as many rows as fit on the screen.
  • The property: visibleRowCountMode defines whether the height of the grid table is fixed or automatically calculated based on the space provided by the underlying container. For automatic calculation, make sure that all rows have the same height.
  • The property: minAutoRowCount defines the minimum number of rows that must be shown if the property: visibleRowCountMode is set to “auto”. Show at least three to five rows.
  • The property: firstVisibleRow defines the first row shown in the visible area of the grid table. The grid table is scrolled accordingly.
  • The property: allowColumnReordering is deprecated. Do not use it. Use the property: enableColumnReordering instead.
  • The property: editable does not have a visible effect. Do not use it.
  • The property: enableGrouping turns the experimental grouping on or off. Handle with care.
  • The property: enableCustomFilter changes the filter entry in the column header menu from an edit box to Filter…. Selecting this entry throws an event to which apps can react, for example, by opening a dialog. In general, you should choose the built-in filter over your own implementation. Specifically, keep filtering via the column header menu simple, while offering more advanced options via the table personalization dialog.
  • The property: enableBusyIndicator has not yet been fully implemented. Do not use it.
  • The property: title adds a line of text on top of the grid table. Do not use this. To add a title to the table, use a toolbar.
  • The property: footer adds a short text at the bottom of the table.
  • The property: Busy sets the grid table to busy state. While in busy state, the whole table cannot be used and items cannot be read due to an overlay.
  • The property: Tooltip does not have an effect. Do not use it.

sap.ui.table.Column

The following additional properties are available for the column:

  • The property: visible defines whether a column is shown or hidden.
  • The property: name defines the name shown in the column header menu for showing and hiding columns. In SAP Fiori, columns are shown and hidden via the table personalization dialog or via the table personalization dialog. Do not use this property.
  • The property: headerSpan defines whether one column header is used for one or several columns. To prevent adverse side effects, always use one column header for only one single column. Do not use this property.
  • The property: Tooltip does not have an effect. Do not use it.

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

Implementation

Tree

Within SAP Fiori, we distinguish between tree tables and trees. Both usually allow the user to display and work with a hierarchical set of items. While tree tables are usually used for more complex data, trees are generally used for rather basic data. Trees are mostly used in the master list section of the split-screen layout and in popovers or dialogs. In certain use cases, they can also be used in full screen layouts.

In the case of tree tables and trees, items that contain additional items are called nodes, while items that do not contain any other items are called leaves. If available, a single topmost node is called a root node. Apart from the hierarchical structure of its nodes and leaves, a tree is quite similar to a list.

Usage

Use the tree if:

  • You need to display the key identifier of hierarchically structured items, for example in the master list of split-screen layouts.
  • Selecting one or more items out of a set of hierarchically structured items is a main use case.
  • The hierarchy has only a small amount of levels (around 5 to 7) and items (around 200).
  • You want to have only one implementation for all devices.

Do not use the tree if:

  • The main use case is to select one item from a very small number of non-hierarchical items, without viewing additional details. In this case, a select or combo box might be more appropriate.
  • Items are not structured hierarchically. Use a list instead.
  • The hierarchy turns out to have only two levels. In this case, use a grouped list.
  • The hierarchy turns out to be just a categorization based on several details of the item. In this case, an analytical table provides multi-level grouping. Note that the analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You need to display deep hierarchies with additional data per item. In this case, use a tree table. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • The structure contains more than 200 items. In this case, use the tree table. It is optimized for large item sets and provides better performance. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You need an overview of a large amount of data. In this case, use a chart.

Check out the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The tree is like a list containing hierarchical data. It acts as a container for items, with the possibility to expand and collapse nodes. When reducing the width, item texts will wrap to ensure that the tree adapts to the new size.

Layout

The title bar (optional) contains the title of the tree. In addition, an item counter and toolbar items can be placed on the title bar.
The collection of hierarchical items occupies the main part of the tree.

Schematic visualization of the tree
Schematic visualization of the tree

Components

The title bar consists of a toolbar. The toolbar can contain a title, an item count, and other toolbar items such as actions or view settings, for example.
The standard tree item consists of:

  • a highlight indicator (optional)
  • an expand/collapse button for nodes
  • a selector in form of a checkbox or a radio button (optional)
  • an icon (optional)
  • a text
  • a counter (optional)
  • additional buttons with actions such as Edit, Navigate, or Delete (optional)
Standard Tree Item
Standard Tree Item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the numbers of items it contains. It does not have a scroll container on its own, but is scrolled together with the page or its parent.

Same tree, with different expand state
Same tree, with different expand state

Selecting

A tree can have one of the following selection modes (sap.m.Tree / sap.m.ListBase, property: mode):

None: Items cannot be selected (sap.m.ListMode.None).
Beware: Items can, nevertheless, use the sap.m.ListType “navigation” which allows click-handling on specific items. This should only be used when the click triggers a navigation to a corresponding item details page.

Tree without selectable items
Tree without selectable items

Single select master: One item of the tree can be selected. To select an item, click anywhere on the item. Single select master does not add any visual indication to the tree and therefore cannot be differentiated from trees without selection if no item is selected. Therefore, always keep one item selected. For single selection, this is the preferred mode. (sap.m.ListMode.SingleSelectMaster)

Single selection: only one item is selected.
Single selection: only one item is selected.

Single select left: One item of the tree can be selected. For this, the tree provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the item triggers something else, such as a navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).

Single selection with radio buttons. Use only if row clicks are used for something else, such as for navigation.
Single selection with radio buttons. Use only if row clicks are used for something else, such as for navigation.

Multi-select: Allows the selection of one or more items. For this, the tree provides checkboxes on the left side of each line item. Each item is selected independently from each other (sap.m.ListMode.MultiSelect).

Multiple selection
Multiple selection

Deleting

To delete single items, use the tree in “delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds a Delete   button to each item. Clicking or tapping this button triggers the deletion of the corresponding item. Do not use this mode if deleting multiple items at once is the preferred use case. Delete is a mode of the tree and  therefore cannot be used together with single selection or multi selection.

Tree in “delete” mode
Tree in “delete” mode

Item Level

Expandable and Collapsible Nodes

To expand or collapse a node, an expandable/collapsible button is provided on each node automatically.

Expand / collapse button
Expand / collapse button

Navigating

To allow navigation from an item, set type to “navigation” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create an indicator at the end of the line (“>”) and the entire item will become selectable. Clicking or tapping the line triggers the navigation event. However, clicking or tapping a selectable area or an expandable/collapse node does not. Use the navigation event to navigate to a new page containing item details.
If no navigation is possible, set type to “inactive”.
Navigation is an item type and therefore cannot be used together with “edit” or in combination with click events for the entire item (“active”).

Tree items with navigation indicator
Tree items with navigation indicator
Navigation indicators can be set per item
Navigation indicators can be set per item

Editing Items

To allow the user to edit an item, set type to “detail” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an edit  button at the end of the line. Clicking the button triggers the edit event. Use this event to either open a dialog or a details page where the item can be edited.
Edit is an item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

Edit button
Edit button

Clicking an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere except when triggering a selection or when expanding/collapsing a node). Apps can react to the event, such as by opening a dialog (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).
Active elements do not have a visual indication and therefore cannot be differentiated from non-active elements.
“Active” is an item type and  therefore cannot be used together with “navigation” or “edit”. In addition, “active” uses the entire item as a clickable area and thus cannot be used together with single select master.

Active items
Active items

Guidelines

Tree vs. List

Trees are more complex than lists due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

Example of an acceptable use of trees
Example of an acceptable use of trees
Do
A clear parent-child relationship
A clear parent-child relationship

Broad vs. Deep Hierarchies

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't
Avoid unnecessary depth in the hierarchy
Avoid unnecessary depth in the hierarchy
Do
Favor breadth over depth in a hierarchy
Favor breadth over depth in a hierarchy

You can use the following methods to reduce hierarchy levels:

  • Avoid a single root node. It is usually not needed.
  • Container nodes at the top level can usually be replaced by tabs or value pickers.
  • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
  • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.
Acceptable: repeat entries to optimize finding items
Acceptable: repeat entries to optimize finding items

Design Concepts

The tree can be used to display hierarchical data. Unfortunately, trees convey an immediate feeling of complexity. Ideally, show trees only if there is no other option. You should instead try the following:

  • Flatten the data. A list is still complex, but less so than a tree. A combo box might also fit in some use cases.
  • When only two levels are needed, a grouped list control can be used. This works well, where group nodes are used for categorizing their children and where the group nodes themselves do not need to be selectable.
  • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Title

If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.
Use a title text if it is not already provided by the surrounding area. Do not use a title text if it would just repeat text that is already in the context above the tree.
Use a title if you need a toolbar. To avoid repeating text, feel free to use generic text as a title, such as Items.
If you use a title, be sure to include the following:

  • A title text for the tree.
  • An (optional) item count using the following format: Title (Number of Items). For example, Items (17). Depending on the use case, either count all items or leaves only (for example, if nodes are mainly used for categorization).
Title
Title
Title with item count
Title with item count

Loading Data

To indicate that the tree is currently loading items, use the busy state (sap.m.Tree, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Tree in busy state while loading data
Tree in busy state while loading data

Initial Display

Think of the initial expandable/collapsible state of a tree. If your structure contains many items on the root level, it might make sense to collapse the whole tree in its initial state.

In contrast, if the most important items are displayed on a deeper level (if, for example, the parent nodes are simply a kind of categorization), the tree should be expanded up to the first level where the most important items immediately appear.

Content

The standard tree item allows you to set one text per item. The text wraps, which can lead to items of different heights depending on the length of the text. An icon can be shown before the text. Try not to use the icons, and only use them if the meaning of the icons is clear and unambiguous. In addition, a counter can be placed on the right side of the item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: counter).

Standard tree item with all options
Standard tree item with all options

Content Formatting

To display object names with an ID, show the ID in brackets after the corresponding object name.

Place the ID in brackets after the corresponding object name
Place the ID in brackets after the corresponding object name

Try not to display an empty tree. If there is no way around this, provide instructions on how to fill the tree with data (sap.m.Tree / sap.m.ListBase, properties: showNoData, noDataText).

Provide meaningful instructions within an empty tree
Provide meaningful instructions within an empty tree

Highlighting Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to show:

  • A semantic state (for example, red or orange if the item contains an error or warning)
  • A neutral state (for example, blue to highlight newly added items)

(sap.m.StandardTreeItem / sap.m.ListIemBase, property: highlight)

Highlighted items
Highlighted items

Item States

To show that an item has been modified, for example within the global edit flow, add the string (Modified) to the text of the item.

A modified item
A modified item

To show that a modified item has an error, for example within the global edit flow, add the string (Contains errors) to the text of the item.

A modified item with an error
A modified item with an error

To show that an item is locked, add the string (Locked by [name]) to the text of the item.

A locked item
A locked item

To show that an item is in a draft state, add the string (Draft) to the text of the item.

Item in draft state
Item in draft state

Show only one state at any one time.

Actions

To trigger actions on items, show the actions on a toolbar above the tree. Do not offer action triggering on multiple items if the tree is expected to have fewer than 10 items in most cases.
The following actions on single items must always be in-line:

Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a delete  button at the end of each item.

Items with Delete button
Items with Delete button

Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.

Items with navigation indicator
Items with navigation indicator

Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an edit   icon at the end of the corresponding items.

Edit button
Edit button

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the tree. For example: Add, Collapse All, Expand All, …

To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Selection and expanding/collapsing a node does not trigger the event, but are handled by the tree. Do not use this for navigation, to switch the line item to an edit state, or to delete the item.
Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection master.

When you add an item, add the new item as the first item of the corresponding node.

Editing Items

To edit items, add an Edit button either in-line on the toolbar above the tree. Triggering the button either opens a dialog or navigates to an editable details page.

For mass editing:

  • Provide multiselection (sap.m.Tree/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
  • Provide an Edit button on the toolbar above the tree.
  • If several items are selected, triggering the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For more details, see mass editing.

Properties

sap.m.Tree

The following additional properties are available for the tree:

  • The property: insert adds a margin on all sides of the tree.
  • The property: footerText adds a small additional row below the last item of the tree. This row can contain text only. Do not use this property.
  • The property: width defines the width of the whole tree.
  • The property: includeItemInSelection uses a click on the entire line item to select the corresponding item if the tree is in a selection mode. This competes with other settings such as “Navigation” or “Active” and should therefore not be used.
  • The property: enableBusyIndicator automatically shows a busy indicator while data is being loaded.
  • The property: modeAnimationOn plays a short animation it the selection mode is changed. Do not use it.
  • The property: showSeparators allows you to show all, none, or some separators. The default setting, which shows all separators, works well in most cases.
  • The property: swipeDirection allows you to define the direction in which to swipe if additional actions are hidden behind a tree item. This works only on touch devices. Do not use this property for functionality which is not available somewhere else.
  • The property: rememberSelections leaves items selected even if they are not currently visible, for example, through filtering. If this behavior is not wanted, set the flag to “false”, but you should do so only in exceptional cases.
  • The property: busy sets the tree to a busy state. While in busy state, the entire tree cannot be used and items cannot be read due to an overlay.
  • The property: busyIndicatorDelay defines the time after which a busy state is shown after the tree has been set to this state. Use the default value.
  • The property: visible shows the tree (“true”) or hides it (“false”).
  • The property: tooltip adds a tooltip to the entire tree. The tooltip is only shown on mouse interaction. It will not work on tablets, smartphones, or other touch devices. Do not use it.

sap.m.StandardTreeItem

The following additional properties are available for sap.m.StandardTreeItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: busy sets the item to a busy state. While in busy state, the whole item cannot be used and cannot be read due to an overlay. In most cases, this should not be needed. Do not use it.
  • The property: busyIndicatorDelay defines the time after which a busy state is shown after the item has been set to this state. Do not use it.
  • The property: visible shows or hides the item.
  • The property: tooltip adds a tooltip to a whole item. The tooltip is only shown on mouse interaction. It will not work on tablets, smartphones, or other touch devices. Do not use it.

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

Implementation

Dialog

The dialog control (sap.m.dialog) interrupts the current app process to prompt the user for information or a response. It is a forced decision or a confirmation that needs to be signed off by the user.

Usage

Use the dialog if:

  • You want to display complex content but don’t want the user to navigate away from the current page.
  • You want to display an additional step or process on the UI, which the user has to confirm via an action at the end.

Do not use the dialog if:

  • You want to display a simple message (use the message box instead)
  • You just want to confirm a successful action.
  • You do not want to interrupt the user’s action.

Responsiveness

The dialog provides different behavior on a smartphone than on a tablet or desktop. You can distinguish between a cozy dialog and a compact dialog. For more information, see content density.

The buttons in the toolbar are aligned differently on the various devices. On a smartphone, they cover the entire footer, but on a tablet or desktop, they are right-aligned.

Size S (Smartphone)

Full Screen Dialog

We recommend displaying dialogs in S size in full screen mode. Most of the content of a dialog is worth opening full screen so the user is able to focus on the content of the dialog. The stretch property can be easily set by the application to true. The toolbar on which actions are placed within a dialog is positioned at the bottom of the dialog.

Full screen dialog (size S)
Full screen dialog (size S)

Position of the Action Buttons

By default, the dialog can have one or two actions, which cover the entire footer on smartphones.

Footer actions alignment (size S)
Footer actions alignment (size S)

When to Open Full Screen or Modal

Message dialogs should always be displayed as modals. There is no need to display a simple message in a full screen dialog. If you want to display a simple message, use the message box instead.

If you use standard dialogs such as value help, you should open them in full screen mode. The device’s entire screen is used to display the dialog, and the user can focus on the content of the message. The dialogs offer a stretch property for full screen behavior.

Size M (Tablet)

By default, the dialog can have up to two action buttons in the footer. The action buttons in the toolbar are right-aligned. Use cozy mode on tablet devices.

If the content height increases or is set to more than the screen height, the dialog height stops at 4 rem from the top and bottom. The user can then scroll through the content area.

Size L (Desktop)

By default, the dialog can have one or two actions. The action buttons on a desktop device are right-aligned. Use compact mode to ensure that the padding and margins are optimized for desktop devices.

If the content height increases or is set to more than the screen height, the dialog height stops at 4 rem from the top and bottom. The user can then scroll through the content area.

Dialog in compact mode (size L)
Dialog in compact mode (size L)

Layout

Position on the Screen

The dialog is positioned in the center of the screen. It opens in a modal window to ensure that it attracts the user’s attention when it displays emergency states.

On a smartphone, the stretch property allows you to achieve full screen behavior.

Behavior and Interaction

Navigation in a Dialog

Navigation in a dialog enables the application to navigate to another page within the dialog. On the second page, an arrow on top of the dialog allows the user to navigate back to the first page.

Navigation example inside the dialog
Navigation example inside the dialog

Resizable

The user can change the size of the dialog by setting the “resizable” property to true. The following figure shows the resizing indicator, which helps the user to identify this functionality.

Resizable indicator on the bottom right-hand corner
Resizable indicator on the bottom right-hand corner

Draggable

Dialogs can be moved by dragging the header to another position. Set the “draggable” property  to ‘true’ and by clicking the title, the user can move the dialog to another position.

Dialog is movable by dragging the title of the dialog
Dialog is movable by dragging the title of the dialog

Messaging in Dialog

Message popovers do not need to be displayed in dialogs. For example, to show an issue with with content in a field, highlighting can be used. For more information, see form field validation.

Highlighted form fields in dialog
Highlighted form fields in dialog

Types

Standard Dialog

Use the standard dialog if you want to display a common dialog. The main visual differences are that the header is displayed with a grey background, and that no icon is shown.

The content can be filled with your application-specific data.

Other Types of Dialogs

Message Box

The message box is a special type of dialog that is used to display messages quickly. For each type of message, the app team can decide when to use a dialog. Use the message toast (sap.m.MessageToast) for success messages. For more information, see message box.

Components

The dialog contains the following sections and options:

Title: Title text appears in the dialog header.

Subheader: When a subheader is assigned to a dialog (optionally), it appears below the main header. As the subheader is not part of the content area, it is not scrollable.

Content: This area contains the actual content of the dialog.

Footer with actions: The footer can contain up to two buttons (optionally).

Example of a dialog structure
Example of a dialog structure

Emphasized Buttons in a Dialog

By emphasizing a button in the dialog toolbar, the user can focus more on the action that the application would see as the standard action. Use an emphasized button if you want to better guide your user.

Usage of an emphasized button in dialog toolbar
Usage of an emphasized button in dialog 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

Implementation

Object Header

Information
Do not use the object header control for the object page floorplan. For object pages, always use the snapping header control.

The object header usually represents an object instance. As such, it contains the most important information a user needs to see in order to understand what the object is about and what its status is. It is the first control on a page dedicated to a single object instance, usually the object view.

The control can also be used as the header of other pages, such as the full screen layout. In that case, the object header contains the most important aggregated information of the items that are listed below.

Usage

Use the object header:

  • As the first component on a page that handles a single object instance to enable the user identify it easily.
  • As the header of other pages, such as the full screen layout. In this case, the object header contains the most important aggregated information of the items that are listed below.

Do not use the object header:

  • Inside the content area as a work-around for visualizing something that is not possible with current means.

Responsiveness

The object header generally adjusts to different screen sizes. To achieve this, there is a built-in rule set that defines which content wraps or truncates when necessary, and how attributes and status texts are arranged depending on the screen size.

The object header has two flags that influence its appearance and resizing behavior: Responsive and FullScreenOptimized.
Object header – Split-screen layout (Responsive = true, FullScreenOptimized = false)
Object header – Split-screen layout (Responsive = true, FullScreenOptimized = false)

Responsive

As of SAPUI5 1.28, the app team should generally set the responsive flag to ‘true’. In this case, the attributes are the first set of entries in the header, followed by the second set of statuses. The on-screen distribution differs from previous SAPUI5 versions. Even if there are many attributes and only a few statuses, use of the space is now optimized as the entries fill the respective columns equally.

Object header – Smartphone size (Responsive = true, FullScreenOptimized = false)
Object header – Smartphone size (Responsive = true, FullScreenOptimized = false)

Full Screen Optimized

The second attribute, FullScreenOptimized, should be activated when the header makes full use of the screen width and is not used in a split-screen layout.

Object header – Full screen optimized (responsive = true, FullScreenOptimized = true)
Object header – Full screen optimized (responsive = true, FullScreenOptimized = true)

Attribute/Status Distribution

The following table shows how the attributes are distributed automatically when the responsive flag is set to ‘true’ on various screen sizes.

Screen Size 2 Attributes 3 Attributes 4 Attributes 5+ Attributes
Desktop (full screen) Next to the title area (1 column of 1-2 attributes) Next to the title area (1 column of 3 attributes) Underneath the title area (4 columns split by 1/1/1/1) Underneath the title area (4 columns split by 2/1/1/1)
Desktop (split screen layout) Underneath (2 columns split by 1/1 Underneath (2 columns split by 2/1) Underneath (2 columns split by 2/2) Underneath (3 columns split by 2/2/1)
Tablet (full screen – landscape) Underneath (2 columns split by 1/1) Underneath (3 columns split by 1/1/1) Underneath (3 columns split by 2/1/1) Underneath (3 columns split by 2/2/1)
Tablet (split screen layout) or Tablet (full screen – portrait) Underneath (2 columns split by 1/1) Underneath (2 columns split by 2/1) Underneath (2 columns split by 2/2) Underneath (2 columns split by 3/2)
Smartphone Underneath (1 column of 1-2 attributes) Underneath (1 column of 3 attributes) Underneath (1 column of 4 attributes) Underneath (1 column of 5+ attributes)

Prior to SAPUI5 1.28 (Responsive Set to ‘False’)

The responsive flag is deactivated by default in apps that were built before SAPUI5 1.28. As mentioned above, this mainly impacts the attributes and status arrangement. If the responsive flag is turned off, all attributes are left-aligned in the object header and all statuses are right-aligned, regardless of their individual number.
The object header still reacts correctly to resizing, but does not make optimal use of the space available.

For example, three attributes and one status with Responsive and FullScreenOptimized both set to ‘false’ results in two columns: the first (left) column contains three attributes, and the other column (right) has one status.  Altogether, this is three rows in height, whereas the same number of entries on a desktop full screen with the two flags set to ‘true’ results in a height of just one row (spread over four columns).

Components

Title

  • The object header has a mandatory title that serves as the key identifier of the object instance (property: title).
  • Long titles wrap once before they truncate on the second line.
  • A title can be actionable (property: titleActionable), in which case, it looks like a link and triggers an event, which usually results in a quick view.
  • An additional icon or image that identifies the object (property: icon) can be shown in front of the title. The icon or image can also be set to actionable (property: IconActionable).
  • Additionally, the title can show a title selector (which is visualized like a menu). It is mainly used to provide navigation targets, allowing the object to be opened in a different app.
Object header (Responsive=false) – Title not actionable
Object header (Responsive=false) – Title not actionable
Object header (Responsive=false) – Title actionable
Object header (Responsive=false) – Title actionable
Object header (Responsive=false) – Title selector
Object header (Responsive=false) – Title selector

Object Number

  • The object number contains the key attribute of the object instance.
  • The object number consists of text that represents the key attribute of an object, usually a number (property: number) and its unit (property: numberUnit). The object number has a semantic color (property: state). The unit inherits the semantic color of its number.
  • As usual in SAP Fiori, the semantic colors available are negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
Object header (Responsive=false) – Negative object number
Object header (Responsive=false) – Negative object number

Object Attribute

  • The object header can contain 0 to n attributes (property: objectAttribute).
  • The attributes are listed first in the list of attributes in the object header.
  • Attributes can be text (property: text) or actionable (property: actionable), in which case, they are rendered similar to links.
Object header (Responsive=false) – Attribute active
Object header (Responsive=false) – Attribute active

Object Status

  • The object header can contain a list of 0 to n object statuses (property: objectStatus).
  • The statuses are listed as the second set of attributes in the object header.
  • The status has a semantic color.
  • Statuses can be text or icons. A combination of the two is technically also possible, in which case, the icon is placed in front of the text. We generally recommend that you use text only (see guidelines below).
  • A progress indicator may also be shown as a status. If used, the progress indicator should be the last item in the list of statuses.
Object header (Responsive=true) – one object marker, three object attributes, and one object status
Object header (Responsive=true) – one object marker, three object attributes, and one object status

Object Marker

The object marker allows you to express the technical status of an object.

  • Objects can be flagged and marked as favorites. The object header provides flags for both (properties: markFavorite, markFlagged).
  • To show them in the object header, you also need to activate the respective flag (property: showMarkers).
  • When they are used and shown, they appear directly behind the title.
  • With version 1.42 an editing status is available in object header. This status is part of draft handling concept. There are four editing statuses – unchanged/active version, draft, locked and unsaved changes.
    • Unchanged: The default status for a saved entity that no one is working on. There is no special indicator for this status on the screen.
    • Draft: A user’s own draft is tagged as Draft.
    • Locked: If a user is editing a business entity, it is locked for other users. The object remains locked until the user has finished editing or until the locking time has passed.
    • Unsaved changes: If the locking time has expired, other users can see that there are unsaved changes by the person who edited the object.
Object header (Responsive=false) – Two object markers, three object attributes, and one object status
Object header (Responsive=false) – Two object markers, three object attributes, and one object status
Object header with three object markers
Object header with three object markers
Object marker - editing status types
Object marker - editing status types

Intro

  • As mentioned above, another component from the early days of SAP Fiori called the intro (property: intro) is available.
  • It is now shown directly below the title in a smaller font size.
  • The intro can call an event if it is set to actionable (property: introActionable).
  • Previously, the intro appeared above the title, and was used to indicate the origin of an object (for example, Forwarded by…, On behalf of …). It now tends to be used as a short subtitle.
Object header (Responsive=true) – Intro text used as subtitle
Object header (Responsive=true) – Intro text used as subtitle
Object header (Responsive=false) – Intro text
Object header (Responsive=false) – Intro text

Condensed

  • The object header provides a condensed flag for cases in which it is used as a page header with little information (property: condensed).
  • When turned on, the object header displays only the title, object number, and one attribute.
Object header – Condensed mode
Object header – Condensed mode

Guidelines

Settings

  • Set the object header responsiveness flag to ‘true’ (property: responsive) to make optimal use of the screen real estate.
  • If your app runs in full-screen mode (not master/details), make optimal use of the header area by setting the respective property to ‘true’ (property: FullScreenOptimized).
  • If you need to enforce the sequence and stable display of the attributes independently of the screen size, such as for an address, you might still decide to set the Responsive property to ‘false’ as an exception.

Title

  • The object header contains a mandatory title, which serves as the key identifier of the object instance (property: title). The title should be easily readable text without any IDs. If an ID is essential to the user, for example, to distinguish between identical titles, it can be put in brackets, such as Product ABC (1234567). If it is usually a long number, you can also consider adding it as a first attribute. In that case, however, you must give it a label (property: title of the Object Attribute).
  • Although the title can be truncated, keep it as short as possible and only as long as necessary.
  • If you make the title actionable and use an image or icon as well, both should be actionable and trigger the same event.
  • If you do use a title selector, it should open an action sheet that allows the user to choose from different options.

Object Number

  • The object number contains the key attribute of the object instance, which is usually a numeric attribute. In rare cases, it can also be used with text if that is the key attribute of the item. Be careful when you use text because it often leads to issues during translation if the text is too long.
  • As usual with SAP Fiori, the semantic colors available are negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
  • For very long numbers, use a formatter.
  • The object number can be left blank if there is no key attribute worth showing.
  • The object number contains the key attribute of the object instance, which is usually a numeric attribute. In rare cases, it can also be used with text if that is the key attribute of the item. Be careful when you use text because it often leads to issues during translation if the text is too long.
  • As usual with SAP Fiori, the semantic colors available are negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
  • For very long numbers, use a formatter.
  • The object number can be left blank if there is no key attribute worth showing.

For more information, see object number.

Object Attribute

  • These object attributes do not generally need a label if it is clear what they refer to. If attributes are not distinct, you can use a label (property: title).
  • To facilitate recognition of the object header, we recommend using no more than four attributes.

For more information, see object attribute.

Object Status

  • Although it is technically possible to show icons together with text, we recommend using text only.
    • Only use icons that are clear and unambiguous. If you think your icon would need a descriptive text to be understood, use text only.
    • In the case of locked items, however, you may also add further information about who has locked the item (when available).
  • The same rule for choosing semantic colors as elsewhere in SAP Fiori applies for the statuses negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
  • In terms of indicating status priority, the general guidance is: very high (property: error), high (property: warning), medium, low, or other (property: none).
  • You can also show a progress indicator as a status. If you use it, the progress indicator should be the last item in the list of statuses.
  • As with the attributes, statuses do not need a label if it is clear what they refer to. If statuses are not distinct, you can use a label (property: title).
  • Here, too, we recommend that you have no more than four entries in the status list (including progress indicators and flag or favorite).

For more information, see object status.

Intro

  • The intro usually contains a short subtitle and should only be used when necessary.
  • Do not use the intro for standard attributes.

Object Marker

An object might contain multiple technical statuses at the same time. However, the editing statuses are mutually exclusive. As a result, an object can have a maximum of 3 technical status visible on the screen: 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.

Flag and Favorite are usually displayed as icon. The same applies to all screen sizes.

The default behavior for the editing status is described below.

On S size:

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

For more information, see object marker.

Master/Details

  • When used in the details area of the split screen (master/details) and the master list contains object list items, the object header should show the same information as the object list item, plus additional information if necessary.
  • Unlike the object list item, the object number uses large number formatting because the object header has more space for handling long text.

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

Implementation

Chart (VizFrame)

Use the sap.viz.ui5.controls.VizFrame control to display different types of charts.  The VizFrame control can display charts containing large sets of values in an interactively rich and responsive way, or it can display charts containing a small amount of data with no interaction.

You can put the VizFrame control inside the ChartContainer SAPUI5 control.  This enables you to place a toolbar above the chart which gives users the ability to switch between a chart view and a table view, as well as switch to full screen mode.

Guidelines

Chart Types:

Colors and Patterns

Interactions:

Additional SAP Fiori Requirements:

Advanced Features:

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

Rating Indicator

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Rating indicator
Rating indicator

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Rating indicator as part of a form
Rating indicator as part of a form

Layout

Context

Use the rating indicator in forms, tables, or in a dialog box.

Rating indicator as part of a form
Rating indicator as part of a form
Rating Indicator as part of a table
Rating Indicator as part of a table
Rating indicator as part of a dialog box
Rating indicator as part of a dialog box

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Details for rating in popover
Details for rating in popover

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

  • Interactive – used for rating an item
  • Disabled

As the non-interactive state (rating result preview) is not currently available, use the disabled state instead.

Types of rating indicator: Interactive and disabled
Types of rating indicator: Interactive and disabled

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Float Values

Float values can be visualized as a half or full star (property: visualMode).

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

  • Small: 1 rem (16 px)
  • Medium: 1.375 rem (22 px) – default
  • Large: 2 rem (32 px)
Possible sizes of rating indicator: small, medium, large
Possible sizes of rating indicator: small, medium, large

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

List

In SAP Fiori, we distinguish between tables and lists. Both usually contain homogeneous data, but lists generally have rather basic data, whereas the data in tables tends to be more complex. Lists are mostly used in the master list section of the master-detail floorplan and in popovers or dialogs, although they can also be used in full-screen floorplans in certain use cases.

Usage

Use the list if:

  • You want to display a homogeneous set of basic data.
  • You need to sort, group, or filter simple data sets.
  • You need to display a single-level hierarchy rather than using a complex tree table to support this simple use case.

Do not use the list if:

  • You want to manage complex data sets that need to be extensively sorted, grouped, filtered, or edited. In this case, you should use the table.
  • You work with complex hierarchies. In this case, you should use a tree.

Responsiveness

The list is like a layout container. You can change its width, but you must also ensure that the items contained in the list adapt whenever the list is resized.

All list item variants available in SAP Fiori already adapt to the respective screen size.

List Item Variants

The list contains various list items. These items can be of various types depending on the use case and on the content they have. SAPUI5 already provides the most common list items in SAP Fiori in the form of controls, although custom list items can also be created if necessary.
All the available list item types behave responsively and adapt to changing screen sizes out of the box. Most of them use truncation if size becomes too limited as they are most often used to navigate to details of the item they currently contain. In the case of custom list items, text wrapping would also be permissible if required.

Object List Item

The object list item is the list item variant used most frequently in SAP Fiori applications. Consisting of a title, key figure, attributes, and a status, it contains the most important information about an object.

The space available for the attributes and status is limited as it should only show crucial information that allows the user to decide which items should be dealt with first.

All essential information about an object is usually provided when the user navigates to the item details.

For more information, see object list item.

Object list items
Object list items

Standard List Item

The standard list item is used for less complex entries, such as when the user selects an item in a dialog. This list item contains an optional image, a title, description, and a single info text (which can contain semantic information).

For more information, see standard list item.

Standard list items
Standard list items

Display List Item

The display list item is the simplest form of a list item and is only capable of showing a label and values. It is seldom used.

For more information, see display list item.

Display list items
Display list items

Action List Item

The action list item allows various actions to be triggered in a dialog. The action list item is not used in the content area.

For more information, see action list item.

Action list item
Action list item

Feed List Item

The feed list item is mainly used in feeds and notes.

For more information, see feed list item.

Feed with feed list items
Feed with feed list items

Input List Item

The input list item allows the user to enter data in a list item. It is seldom used in SAP Fiori apps as forms are usually a more preferable method of entering data.

For more information, see input list item.

Input list item
Input list item

Components

The list control comes with the following main properties:

Header

The header text contains the title of the list. It is usually only used when the list is in the content area.

Footer

The footer text is the last entry in the list, and as such, it scrolls away with the content. Therefore, this property is also seldom used.

Lazy Loading

Like the table, the list also allows lazy loading. The “growing” list property is used for this purpose.

List with header and footer
List with header and footer

Empty List

The noDataText property is used if the list contains no entries. A generic “No Data” text is set by default, but we recommend using specific text if possible.

Empty list
Empty list

Count

List items can have a count, which is located on the far right of a row. It can be used in simple lists, such as those that contain standard list items, to indicate how many subitems the user can expect when navigating on the item.

Standard list items with counter
Standard list items with counter

Read/Unread

You can set an indicator to highlight unread items, making it easier for the user to discover them (property: showUnread = true). If you set this indicator, all texts for the unread items are shown in bold font.

By default, this indicator is switched off, and all list items are displayed in normal font.

Display list item with read and unread items
Display list item with read and unread items

Highlighting Items

To show that an item needs attention, a highlight indicator can be shown in front of the item. The highlight indicator can be used to show:

  • A semantic state (for example, red or orange if the item contains an error or warning)
  • A neutral state (for example, blue to highlight newly added items)

(property: highlight)

Display list item with read and unread items
Display list item with read and unread items

Behavior and Interaction

There are several ways to interact with the list and its list items:

Mode

The list can have several modes. The respective property (Mode) allows the following methods of selection:

  • None
  • SingleSelectMaster (used to pick one item with no additional indicator, as used in the master list)
  • SingleSelectLeft (used to pick one item using a radio button on the far left)
  • MultiSelect (used to pick several items from the list using checkboxes on the far left)
  • Delete (used to delete items from the list using a delete indicator on the far right)
List with multiple selection
List with multiple selection
List with explicit single selection
List with explicit single selection
List with delete mode
List with delete mode

Grouping

List items can be grouped. The group header is a visually separate line at the top of the items it groups. It does not currently provide an interaction of its own.

Grouped list
Grouped list

Type

The list item type defines the interaction of the list item, which is accompanied by a visual cue.

The items can be one of the following:

  • Active (click event; cursor changes to indicate that)
  • Inactive (no click event; cursor does not change)
  • Navigation (a small arrow appears on the far right, indicating that clicking would navigate)
  • Detail (a pen appears on the far right, indicating that something can be changed there. The user can only click on the pen.)
  • Detail and active (same as “detail”, but also item itself is clickable)

The example opposite shows a visualization of all these types.

All list item types: inactive, detail, navigation, active, detail and active
All list item types: inactive, detail, navigation, active, detail and active

Swipe

You can also provide a swipe feature (SwipeDirection) for quickly approving or deleting items without having to look at the details. It must only be provided as an addition and not be the only way of performing the action.

List with swipe action
List with swipe action

Styles

The list items can have a header when they are used in a content area. It is also technically possible to change the background of the header and of the list itself. Depending on the use case, the lines between the list items and around the list can also be shown or hidden.

The property Show Separators (All, Inner, None) allows only the outer lines (Inner) or all the lines (None) to be hidden when the list is used as a more structural element within a content area.

List showing no separators
List showing no separators

Guidelines

Text Length

When you use the list in the master area, keep the texts as short as possible and only as long as necessary. If you expect large numbers, use formatting instead.

Custom List Items

If none of the list items provided suits the requirements of your app, a custom list item can also be created. If you choose this option, ensure that the custom list item is responsive when resized.

Radio Button

Only use radio buttons if absolutely necessary. One such example is if you want to distinguish single selection from navigation. This is a rare case in which visible radio buttons for single selection are allowed.

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

Implementation

Input Field

Warning
This article was written for an earlier guideline release, and may contain outdated content. An update is in progress. If you have any questions in the meantime, please post them in our SAP User Experience Community forum. Thank you!

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.

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 make a single selection 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:

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
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
Tabular autocomplete suggestion feature on a tablet

Size L (Desktops)

Compact mode:

The full table is shown in the suggest feature.

Tabular autocomplete suggestion feature on a desktop
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.

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:

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 state
Default state
Warning state
Warning state
Error state
Error state
Success state
Success state

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.

  1. None (default): No value state message is shown.
  2. Warning
  3. Error
  4. Success: No value state message is shown.

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

Default
Default
Warning
Warning
Error
Error
Success
Success

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
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
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):

  1. Editable: This is the default setting.
  2. Not editable: The input field is not shown; only the value is shown. This is used in display-only forms.
  3. 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
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
Right alignment
Right alignment

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:

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
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
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
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:

See a live example of tabular autocomplete suggestions.

Tabular autocomplete
Tabular autocomplete

Guidelines

Always provide a meaningful label for any input field.

Maximum Length

Limit the length of the input field. For example, if you expect the user to enter a two-digit number, limit the maximum length to two. The maximum permissible character length is not defined by default. If the backend has a limit, ensure that you set this property accordingly.

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

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 data set 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 and Edit actions
Input field – New and Edit actions

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

Implementation

Progress Indicator

The progress indicator visualizes the current advancement of a process or a degree of accomplishment. The inside of the progress indicator is filled with color to indicate the state of progress. The advancement depends on the specific process. The progress is shown either using absolute numbers or the current percentage of completion together with a progress bar.

Within SAP Fiori, the progress indicator is used as a “meter” or mini chart. It indicates a current object status and is not related to any process that is currently running.

Usage

Use the progress indicator if:

  • You need to visually show a current (static) status.
  • You need to visually strengthen a current (static) status.
  • You need to make different states comparable to each other at a higher level.

Do not use the progress indicator if:

  • Visual feedback is needed for an ongoing operation. In this case, use a busy indicator instead.

Responsiveness

The progress indicator itself is not responsive. It supports the cozy and compact form factors. The compact form factor is used for apps that run on a device operated by a mouse and keyboard. For more information, see Content Density (Cozy and Compact).

Progress indicator in compact mode
Progress indicator in compact mode
Progress indicator in cozy mode
Progress indicator in cozy mode

Layout

Show the current progress as a percentage value between 0% and 100%. Property: percentValue.

Progress indicator displaying 10% progress
Progress indicator displaying 10% progress
Progress indicator displaying 50% progress
Progress indicator displaying 50% progress
Progress indicator displaying 80% progress
Progress indicator displaying 80% progress

Alternatively, you can show the current progress as text in addition to the bar. In this case, the text is shown on the right of the bar if the progress is 50% or less. In all other cases, the progress is shown right-aligned on the bar itself. Property: showValue.

Textual presentation for progress of 50% or less
Textual presentation for progress of 50% or less
Textual presentation for progress of more than 50%
Textual presentation for progress of more than 50%
Progress indicator without textual representation
Progress indicator without textual representation

You also have the option of showing any application-specific text instead of a percentage. Property: displayValue.

App-specific textual representation of progress
App-specific textual representation of progress

Styles

The progress indicator can be enabled or disabled. Property: enabled.

Disabled progress indicator
Disabled progress indicator

The progress indicator can visualize different value states that are represented by various theme-dependent semantic colors. The states are: normal, success, warning, and error. Property: state.

Progress indicator in normal state
Progress indicator in normal state
Progress indicator in success state
Progress indicator in success state
Progress indicator in warning state
Progress indicator in warning state
Progress indicator in error state
Progress indicator in error state

Guidelines

Use the progress indicator to add clarity and weight to an important state that needs to be perceived very quickly.

Progress indicator used for status display
Progress indicator used for status display

Always provide a label for the progress indicator.

Exception: If the progress indicator is used as a single control inside a cell of a responsive table, the column header text is used as a label.

Progress indicator in a responsive table
Progress indicator in a responsive table

Use a group of up to five bars to help users compare different states at a high level. Note that in a group of more than five bars, slight differences are much harder to perceive than a numeric display.

If the user has to compare a group of values, be sure to use the same visual display for all of them (only bars or only numbers).

Group of progress indicators
Group of progress indicators

Progress indicators are typically used within (but not restricted to) the following controls:

Do not disable a progress indicator. A progress indicator is not interactive, therefore disabling it has no effect.

Exception: The progress indicator is shown inside a disabled UI area, such as a completely disabled form or panel.

Properties

The following additional properties are available for the progress indicator:

  • The property “width” defines the width of the progress indicator. The property “height” defines the height of the progress indicator. Adapt it only if the default height does not fit into the surrounding context. Do not use a height below 1.5 rems if text is shown inside the progress indicator.
  • The property “textDirection” is used for localiaztion (right-to-left languages).
  • The property “busy” sets the progress indicator to busy state.
  • The property “visible” shows or hides the progress indicator.
  • The property “tooltip” does not have an effect.

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

Implementation

Tree

With SAP Fiori, we distinguish between tree tables and trees. Both usually allow the user to display and work with a hierarchical set of items. While tree tables are usually used for more complex data, trees are generally used for rather basic data. Trees are mostly used in the master list section of the split-screen layout and in popovers or dialogs. In certain use cases, they can also be used in full screen layouts.

In the case of tree tables and trees, items that contain additional items are called nodes, while items that do not contain any other items are called leaves. If available, a single topmost node is called a root node. Apart from the hierarchical structure of its nodes and leaves, a tree is quite similar to a list.

Usage

Use the tree if:

  • You need to display the key identifier of hierarchically structured items, for example in the master list of split-screen layouts.
  • Selecting one or more items out of a set of hierarchically structured items is a main use case.
  • The hierarchy has only a small amount of levels (around 5 to 7) and items (around 200).
  • You want to have only one implementation for all devices.

Do not use the tree if:

  • The main use case is to select one item from a very small number of non-hierarchical items, without viewing additional details. In this case, a select or combo box might be more appropriate.
  • Items are not structured hierarchically. Use a list instead.
  • The hierarchy turns out to have only two levels. In this case, use a grouped list.
  • The hierarchy turns out to be just a categorization based on several details of the item. In this case, an analytical table provides multi-level grouping. Note that the analytical table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You need to display deep hierarchies with additional data per item. In this case, use a tree table. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • The structure contains more than 200 items. In this case, use the tree table. It is optimized for large item sets and provides better performance. Note that the tree table is not fully responsive. It is only available for desktops and tablets, so you will need to take an adaptive approach by offering an additional UI for smartphones.
  • You need an overview of a large amount of data. In this case, use a chart.

Check out the table overview to decide which SAP Fiori table is most suitable for your needs.

Responsiveness

The tree is like a list containing hierarchical data. It acts as a container for items, with the possibility to expand and collapse nodes. When reducing the width, item texts will wrap to ensure that the tree adapts to the new size.

Layout

The title bar (optional) contains the title of the tree. In addition, an item counter and toolbar items can be placed on the title bar.
The collection of hierarchical items occupies the main part of the tree.

Schematic visualization of the tree
Schematic visualization of the tree

Components

The title bar consists of a toolbar. The toolbar can contain a title, an item count, and other toolbar items such as actions or view settings, for example.
The standard tree item consists of an expand/collapse button for nodes, a selector in form of a checkbox or a radio button (optional), an icon (optional), a text, a counter (optional), and additiona buttons with actions such as Edit, Navigate, or Delete (optional).

Standard Tree Item
Standard Tree Item

Behavior and Interaction (incl. Gestures)

Tree Level

Scrolling

The height of the tree is defined by the numbers of items it contains. It does not have a scroll container on its own, but is scrolled together with the page or its parent.

Same tree, with different expand state
Same tree, with different expand state

Selecting

A tree can have one of the following selection modes (sap.m.Tree / sap.m.ListBase, property: mode):

None: Items cannot be selected (sap.m.ListMode.None).
Beware: Items can, nevertheless, use the sap.m.ListType “navigation” which allows click-handling on specific items. This should only be used when the click triggers a navigation to a corresponding item details page.

Tree without selectable items
Tree without selectable items

Single select master: One item of the tree can be selected. To select an item, click anywhere on the item. Single select master does not add any visual indication to the tree and therefore cannot be differentiated from trees without selection if no item is selected. Therefore, always keep one item selected. For single selection, this is the preferred mode. (sap.m.ListMode.SingleSelectMaster)

Single selection: only one item is selected.
Single selection: only one item is selected.

Single select left: One item of the tree can be selected. For this, the tree provides radio buttons on the left side of each line item. Use this selection mode only if clicking on the item triggers something else, such as a navigation. Ideally, always keep one item selected, even in initial state (sap.m.ListMode.SingleSelectLeft).

Single selection with radio buttons. Use only if row clicks are used for something else, such as for navigation.
Single selection with radio buttons. Use only if row clicks are used for something else, such as for navigation.

Multi-select: Allows the selection of one or more items. For this, the tree provides checkboxes on the left side of each line item. Each item is selected independently from each other (sap.m.ListMode.MultiSelect).

Multiple selection
Multiple selection

Deleting

To delete single items, use the tree in “delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This adds a Delete   button to each item. Clicking or tapping this button triggers the deletion of the corresponding item. Do not use this mode if deleting multiple items at once is the preferred use case. Delete is a mode of the tree and  therefore cannot be used together with single selection or multi selection.

Tree in “delete” mode
Tree in “delete” mode

Item Level

Expandable and Collapsible Nodes

To expand or collapse a node, an expandable/collapsible button is provided on each node automatically.

Expand / collapse button
Expand / collapse button

Navigating

To allow navigation from an item, set type to “navigation” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This will create an indicator at the end of the line (“>”) and the entire item will become selectable. Clicking or tapping the line triggers the navigation event. However, clicking or tapping a selectable area or an expandable/collapse node does not. Use the navigation event to navigate to a new page containing item details.
If no navigation is possible, set type to “inactive”.
Navigation is an item type and therefore cannot be used together with “edit” or in combination with click events for the entire item (“active”).

Tree items with navigation indicator
Tree items with navigation indicator
Navigation indicators can be set per item
Navigation indicators can be set per item

Editing Items

To allow the user to edit an item, set type to “detail” within the corresponding item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail or sap.m.ListType.DetailAndActive). This will create an edit  button at the end of the line. Clicking the button triggers the edit event. Use this event to either open a dialog or a details page where the item can be edited.
Edit is an item type and therefore cannot be used together with “navigation” or in combination with click events for the entire item (“active”).

Edit button
Edit button

Clicking an Item

Items as a whole can be clickable. An event is fired by clicking on the item (anywhere except when triggering a selection or when expanding/collapsing a node). Apps can react to the event, such as by opening a dialog (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active or sap.m.ListType.DetailAndActive).
Active elements do not have a visual indication and therefore cannot be differentiated from non-active elements.
“Active” is an item type and  therefore cannot be used together with “navigation” or “edit”. In addition, “active” uses the entire item as a clickable area and thus cannot be used together with single select master.

Active items
Active items

Guidelines

Tree vs. List

Trees are more complex than lists due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

Example of an acceptable use of trees
Example of an acceptable use of trees
Do
A clear parent-child relationship
A clear parent-child relationship

Broad vs. Deep Hierarchies

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't
Avoid unnecessary depth in the hierarchy
Avoid unnecessary depth in the hierarchy
Do
Favor breadth over depth in a hierarchy
Favor breadth over depth in a hierarchy

You can use the following methods to reduce hierarchy levels:

  • Avoid a single root node. It is usually not needed.
  • Container nodes at the top level can usually be replaced by tabs or value pickers.
  • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
  • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.
Acceptable: repeat entries to optimize finding items
Acceptable: repeat entries to optimize finding items

Design Concepts

The tree can be used to display hierarchical data. Unfortunately, trees convey an immediate feeling of complexity. Ideally, show trees only if there is no other option. You should instead try the following:

  • Flatten the data. A list is still complex, but less so than a tree. A combo box might also fit in some use cases.
  • When only two levels are needed, a grouped list control can be used. This works well, where group nodes are used for categorizing their children and where the group nodes themselves do not need to be selectable.
  • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Title

If needed, implement the title text by adding a title to a toolbar. Place the toolbar above the tree.
Use a title text if it is not already provided by the surrounding area. Do not use a title text if it would just repeat text that is already in the context above the tree.
Use a title if you need a toolbar. To avoid repeating text, feel free to use generic text as a title, such as Items.
If you use a title, be sure to include the following:

  • A title text for the tree.
  • An (optional) item count using the following format: Title (Number of Items). For example, Items (17). Depending on the use case, either count all items or leaves only (for example, if nodes are mainly used for categorization).
Title
Title
Title with item count
Title with item count

Loading Data

To indicate that the tree is currently loading items, use the busy state (sap.m.Tree, property: busy). Do not show any items or text. As soon as the data is loaded, remove the busy state and show all items.

Tree in busy state while loading data
Tree in busy state while loading data

Content

The standard tree item allows you to set one text per item. The text wraps, which can lead to items of different heights depending on the length of the text. An icon can be shown before the text. Try not to use the icons, and only use them if the meaning of the icons is clear and unambiguous. In addition, a counter can be placed on the right side of the item (sap.m.StandardTreeItem / sap.m.ListItemBase, property: counter).

Standard tree item with all options
Standard tree item with all options

Content Formatting

To display object names with an ID, show the ID in brackets after the corresponding object name.

Place the ID in brackets after the corresponding object name
Place the ID in brackets after the corresponding object name

Try not to display an empty tree. If there is no way around this, provide instructions on how to fill the tree with data (sap.m.Tree / sap.m.ListBase, properties: showNoData, noDataText).

Provide meaningful instructions within an empty tree
Provide meaningful instructions within an empty tree

Item States

To show that an item has been modified, for example within the global edit flow, add the string (Modified) to the text of the item.

A modified item
A modified item

To show that a modified item has an error, for example within the global edit flow, add the string (Contains errors) to the text of the item.

A modified item with an error
A modified item with an error

To show that an item is locked, add the string (Locked by [name]) to the text of the item.

A locked item
A locked item

To show that an item is in a draft state, add the string (Draft) to the text of the item.

Item in draft state
Item in draft state

Show only one state at any one time.

Actions

To trigger actions on items, show the actions on a toolbar above the tree. Do not offer action triggering on multiple items if the tree is expected to have fewer than 10 items in most cases.
The following actions on single items must always be in-line:

Delete: Use “Delete” mode (sap.m.Tree / sap.m.ListBase, property: mode, value: sap.m.ListMode.Delete). This places a delete  button at the end of each item.

Items with Delete button
Items with Delete button

Navigation: Use the “Navigation” item type (sap.m.StandardTreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Navigation). This places a navigation indicator at the end of the corresponding items. Use this to navigate to a new page containing item details.

Items with navigation indicator
Items with navigation indicator

Edit: Use the “Detail” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Detail). This places an edit   icon at the end of the corresponding items.

Edit button
Edit button

From these three actions (delete, navigation, and edit), you can combine delete and edit, or delete and navigation. Edit and navigation cannot be combined.

To trigger actions that are independent of the selection, show the actions on a toolbar above the tree. For example: Add.

To trigger a default action on the entire item, use the “Active” or “DetailAndActive” item type (sap.m.TreeItem / sap.m.ListItemBase, property: type, value: sap.m.ListType.Active). Active items trigger an event when clicked, which can be handled by apps, for example, to open a dialog. Selection and expanding/collapsing a node does not trigger the event, but are handled by the tree. Do not use this for navigation, to switch the line item to an edit state, or to delete the item.
Active can be combined with edit and delete, but not with navigation. Do not combine active with single selection master.

When you add an item, add the new item as the first item of the corresponding node.

Editing Items

To edit items, add an Edit button either in-line on the toolbar above the tree. Triggering the button either opens a dialog or navigates to an editable details page.

For mass editing:

  • Provide multiselection (sap.m.Tree/ sap.m.ListBase, property: mode, value: sap.m.ListMode.MultiSelect).
  • Provide an Edit button on the toolbar above the tree.
  • If several items are selected, triggering the Edit button opens a dialog in which the user edits the corresponding fields for all selected items.

For more details, see mass editing.

Properties

sap.m.Tree

The following additional properties are available for the tree:

  • The property: insert adds a margin on all sides of the tree.
  • The property: footerText adds a small additional row below the last item of the tree. This row can contain text only. Do not use this property.
  • The property: width defines the width of the whole tree.
  • The property: includeItemInSelection uses a click on the entire line item to select the corresponding item if the tree is in a selection mode. This competes with other settings such as “Navigation” or “Active” and should therefore not be used.
  • The property: enableBusyIndicator automatically shows a busy indicator while data is being loaded.
  • The property: modeAnimationOn plays a short animation it the selection mode is changed. Do not use it.
  • The property: showSeparators allows you to show all, none, or some separators. The default setting, which shows all separators, works well in most cases.
  • The property: swipeDirection allows you to define the direction in which to swipe if additional actions are hidden behind a tree item. This works only on touch devices. Do not use this property for functionality which is not available somewhere else.
  • The property: rememberSelections leaves items selected even if they are not currently visible, for example, through filtering. If this behavior is not wanted, set the flag to “false”, but you should do so only in exceptional cases.
  • The property: busy sets the tree to a busy state. While in busy state, the entire tree cannot be used and items cannot be read due to an overlay.
  • The property: busyIndicatorDelay defines the time after which a busy state is shown after the tree has been set to this state. Use the default value.
  • The property: visible shows the tree (“true”) or hides it (“false”).
  • The property: tooltip adds a tooltip to the entire tree. The tooltip is only shown on mouse interaction. It will not work on tablets, smartphones, or other touch devices. Do not use it.

sap.m.StandardTreeItem

The following additional properties are available for sap.m.StandardTreeItem:

  • The property: selected allows an item to be selected programmatically.
  • The property: busy sets the item to a busy state. While in busy state, the whole item cannot be used and cannot be read due to an overlay. In most cases, this should not be needed. Do not use it.
  • The property: busyIndicatorDelay defines the time after which a busy state is shown after the item has been set to this state. Do not use it.
  • The property: visible shows or hides the item.
  • The property: tooltip adds a tooltip to a whole item. The tooltip is only shown on mouse interaction. It will not work on tablets, smartphones, or other touch devices. Do not use it.

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

Implementation

Chart Toolbar

The chart toolbar acts as a container for charts.

The width and height of the chart container are never defined by the app, but are always set by the container itself (as explained in Size of the Chart Container).

The toolbar is mandatory. Small charts such as dashboards, table cells, and small frames are an exception to this rule. In these cases, the developer must provide a consistent UI to enable action on the chart.

The toolbar is always placed on top of the chart. It provides actions such as multiple box selection for selecting dimensions, full screen format, personalization actions, and a toggle function for showing and hiding legends.

Responsiveness

The chart container uses the sap.m.OverflowToolbar control. It is a container based on sap.m.Toolbar that provides overflow when its content does not fit in the visible area. For more information, please refer to the toolbar overview article (under Responsiveness).

Chart toolbar – Size L
Chart toolbar – Size L
Chart toolbar – Size S
Chart toolbar – Size S

Components

The chart toolbar can contain the following components:

  • App-specific actions
  • Generic actions

 

The following actions are generic:

  • Perspective switch or chart/title
  • View switch
  • Legend
  • Personalization
  • Zoom in/zoom out
  • Full screen mode
  • Overflow
Components of the chart toolbar
Components of the chart toolbar

Behavior and Interaction

App-Specific Actions

If needed, the app team can define their own actions for the app using icon buttons only. These actions are placed explicitly on the UI, although this is due to change at a later stage.

App-specific actions
App-specific actions

Perspective Switch/Title (Generic)

Chart toolbar overview
Chart toolbar overview

The perspective switch is left-aligned in the toolbar when a generic dropdown or select control is used. It can be used to switch between different dimensions.

For SAP Smart Business apps, the view incorporates and defines the chart description, the dimension, the measure, and the defaulted chart type. The various views are preconfigured and maintained by an SAP Smart Business administrator.

Ensure that all switches have a meaningful title. We recommend that you use a short chart description followed by the dimensions:

by

Simple perspective
Simple perspective

You also have the option of extending the perspective switch if the app needs to switch between specific subdimensions. The number of dimensions and subdimensions that are needed depends on the app.

In general, you can use any kind of control. However, we recommend using the select control.

by

Perspective view with subdimension
Perspective view with subdimension

If the app does not need a perspective switch, use the chart title (property: title).

Chart with title
Chart with title

View Switch (Generic)

View switches are right-aligned in the toolbar. They allow the user to switch between different chart types or table layouts. You need to offer the view switch if the chart relies on subtle color differences or color gradients. Users with visual impairments can then use the table view.

Switches are optional. The buttons can be hidden if there is no need to switch between different charts or tables.

You need to be careful when choosing the chart types and the number of switches. For each app, you must decide which chart types are best suited to visualizing data in the user’s context.

We recommend using no more than three types of visualization. The sequence of chart type switches is not fixed, although we recommend sorting them by importance and usage within the respective app.

The segmented button control is used to display the chart types. The control highlights the chart that is currently displayed.

Chart toolbar with view switch
Chart toolbar with view switch

View Switch – Switch Between Chart and Table

The view switch allows you to switch easily between tables and charts.

Some actions are only available in certain views. For example, the Legend icon is only visible in the chart view. If the user selects the table view, the Filter action is visible and the Legend icon is hidden.

Icon Usage

Each visualization of a chart is represented by an icon.

Bar chart:
Bar chart: "SAP-icons" font - Unicode: #e02c - Name: horizontal-bar-chart
Horizontal bullet chart:
Horizontal bullet chart: "SAP-icons" font - Unicode: #e215
Vertical bullet chart:
Vertical bullet chart: "SAP-icons" font - Unicode: #e216
Combined column line chart:
Combined column line chart: "SAP-icons" font - Unicode: #e11f - Name: business-objects-experience
Stacked bar chart:
Stacked bar chart: "SAP-icons" font - Unicode: #e183 - Name: horizontal-stacked-chart
Stacked column 100% chart:
Stacked column 100% chart: "SAP-icons" font - Unicode: #e180 - Name: full-stacked-column-chart
Bar chart:
Bar chart: "SAP-icons" font - Unicode: #e182 - Name: horizontal-bar-chart-2
Column chart:
Column chart: "SAP-icons" font - Unicode: #e0ef - Name: vertical-bar-chart
Pie chart:
Pie chart: "SAP-icons" font - Unicode: #e015 - Name: pie-chart
Stacked bar 100% chart:
Stacked bar 100% chart: "SAP-icons" font - Unicode: #e17f - Name: full-stacked-chart
Table chart:
Table chart: "SAP-icons" font - Unicode: #e0bb - Name: table-chart
Heatmap:
Heatmap: "SAP-icons" font - Unicode: #e214
Bubble chart:
Bubble chart: "SAP-icons" font - Unicode: #e18e - Name: bubble-chart
Column chart:
Column chart: "SAP-icons" font - Unicode:  - Name: vertical-bar-chart-2
Donut chart:
Donut chart: "SAP-icons" font - Unicode: #e213
Scatter chart:
Scatter chart: "SAP-icons" font - Unicode: & #xe18f; - Name: scatter-chart
Stacked column chart:
Stacked column chart: "SAP-icons" font - Unicode: #e184 - Name: vertical-stacked-chart
Map:
Map: "SAP-icons" font - Unicode: #e185 - Name: choropleth-chart

Legend (Generic)

The chart Legend button (property: ShowLegend) is placed next to the view switches. The user clicks or taps this button to hide or show the legend.

The legend also allows the user to select or deselect data points.

Icon Usage

The legend is represented by the following icon:

Chart legend icon
Chart legend icon

Personalization (Generic)

Developers can add a Personalization button to the app’s chart toolbar to enable app-specific personalization charting (property: ShowPersonalization). The corresponding popover and details also need to be implemented by the developer.

We do not recommend using this feature. If you do choose to use it, exercise caution as the toolbar’s perspective switch feature already allows the preconfiguration of several combinations of dimensions, measures, and selections of chart types.

Hence, the developer should decide on the most valuable chart/dataset combinations for the end user beforehand.

When viewing charts, users do not usually want to think about what chart types, dimensions, or measures are most suitable in a particular use case. Therefore, the app should provide users with the most appropriate preconfigured chart view.

Chart personalization action
Chart personalization action

Icon Usage

Personalization is represented by the following icon:

Chart personalization icon
Chart personalization icon

Zoom In/Zoom Out (Generic)

The app developer can add Zoom In and Zoom Out buttons to the chart toolbar to provide zoom functionality. Two icon buttons depicting a magnifying glass are then displayed. These buttons are positioned just to the left of the full-screen icon and they automatically drive the zoom feature in the chart. When the user clicks or taps the Zoom In or Zoom Out icon, the chart automatically zooms in or out to the most appropriate scale.

Chart with zoom in/out buttons
Chart with zoom in/out buttons

Icon Usage

The zoom in/out functionality is represented by the following icons:

Chart zoom in/out icons
Chart zoom in/out icons

Full Screen Mode (Generic)

Alternatively, the app can use the full-screen mode of the chart container (property: FullScreen). However, the full-screen button is always placed at the top right of the toolbar. Further details are available in the Behavior and Interaction section above.

The user can toggle between embedded and full-screen mode via the Maximize full-screen toggle button. In full-screen mode, the toolbar replaces the page header bar which is usually used (the Minimize icon appears).

In full-screen mode, the chart and toolbar occupy the entire width and height.

Icon Usage

The user clicks or taps the full-screen chart icon to initiate full-screen mode. This icon is then replaced by an icon that allows the user to exit full-screen mode.

Full screen chart icon
Full screen chart icon
Exit full screen chart icon
Exit full screen chart icon

Overflow (Generic)

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

Guidelines

Please see the detailed Guidelines section of the toolbar overview article.

Additional Guidelines

  • Think carefully about what actions you really need in the chart toolbar – do not overload the table toolbar with actions.
  • Try to put the actions as close to the content as possible.
  • Use tooltips like Sort, Filter, and Group to label icon buttons in the table toolbar.

Resources

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

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.
  • They can be specific to the current object (user selects one item).
  • They can apply to a set of items (user selects two or more items).
  • They can control the settings of the UI, which affects all items.
Types of actions (from left to right): Not related to a specific item/object; actions are specific to the current object; actions apply to a set of (selected) items; actions that control the settings of the UI
Types of actions (from left to right): Not related to a specific item/object; actions are specific to the current object; actions apply to a set of (selected) items; actions that control the settings of the UI

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 S
Responsive table toolbar – Size L
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

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. Elements that belong to a group are not allowed to have “always overflow” or “never overflow” as priorities because 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 desktop without overflow
Table toolbar on smartphone with overflow
Table toolbar on smartphone with overflow
Table toolbar on smartphone with open 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.

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
Header Toolbar with Edit and Delete Action

Footer Toolbar

Footer toolbar with transparent standard buttons and emphasized
Footer toolbar with transparent standard buttons and emphasized

Table Toolbar

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

Chart Toolbar

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

Info Bar

Info bar in filtered master list
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

Implementation

Tree Table

A tree table contains a hierarchical set of data structured in rows and columns and grouped into nodes. The analytical table, or ALV, can also provide additional details in several non-hierarchical columns per line item. 

Usage

Trees are used to display and work with large amounts of hierarchical data. They have a high data density and therefore convey an immediate feeling of complexity. Ideally, you should only show trees with a lot of hierarchical data as a last resort. Try the following instead:

  • Break down the data into manageable chunks and allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Responsiveness

A tree table is available for desktops and tablets, but not in smartphone sizes. It supports touch devices, but is not optimized for small screens.

If you use a tree table, note that you have to implement a fallback solution for small screens. This fallback solution does not need to support all use cases.

Possible fallback solutions are as follows:

  • Use navigation to different pages instead of a tree structure. This works well for structures that are no more than four levels deep.
  • Remove levels until only one or two remain. Replace a single-level tree by a table, and a two-level tree by a grouped table or a split-screen layout.
  • Use filtering instead of a tree structure.

You can try to create a fallback based on these ideas, but a completely different solution, such as showing charts in a read-only case, might be more appropriate.

Tree table shown on a desktop
Tree table shown on a desktop
Tree table shown on a tablet
Tree table shown on a tablet

Types

Like all SAP Fiori controls, the tree table is shown in compact mode on a desktop and in cozy mode on tablets.

For a desktop, you can also display even more rows on the same screen height by adding the condensed mode in addition to the compact mode. This renders less white space for each item.

Note that the condensed content density has always to be set in addition to compact. Do not use condensed on its own. Do not mix condensed with cozy. Doing so could lead to unpredictable and / or unwanted results, e.g. cozy sized controls in condensed sized containers, missing padings, etc.

Note that neither compact mode nor condensed mode can be interacted with via touch. Even on a desktop with a touch screen, users will have difficulty selecting rows or using controls inside the cells when using their fingers.

Furthermore, condensed mode is not available for Internet Explorer 9. If condensed mode is to be used, please provide a fallback.

For more information on cozy and compact modes, see content density.

Compact Mode

Tree table - Compact mode
Tree table - Compact mode

Condensed Mode

Tree table - Condensed mode
Tree table - Condensed mode

Components

Column Header

The column header provides the label for the corresponding column and access to the column header menu.

Resizing columns works in the following ways:

  • Mouse interaction: Dragging the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells of this column contain one of the following controls: text, label, link, or input.
  • Touch interaction: The user clicks or taps the column header to reveal two buttons: one for showing the column header menu and one for resizing. Drag the latter to resize the column.

After resizing a column, the adaptation of the column widths depends on how the column width is set:

  • If column widths are set in pixel-based units (px, em, rem), the corresponding column is adapted and following columns are moved accordingly. The width of all other columns is not affected.
    If all the columns together take up less width than the table control, an empty space is added. If all the columns together take up more width than the table control, a scrollbar appears.
  • If all column widths are set in percentage or “auto”, resizing one column might also lead to the automatic resizing of some or all other columns. The position of the resized column might also be affected. This is done to ensure that the whole table width is used and no white space is added. A scrollbar appears only, if all or most of the columns get very small. To avoid the unintended side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

Columns can be rearranged by dragging the column header to another position (sap.ui.table.TreeTable, property: enableColumnReordering).

Tree table – Column header
Tree table – Column header
Opening the column header menu on touch devices
Opening the column header menu on touch devices
Less columns than space available
Less columns than space available

Line Item

A line item contains a set of cells and provides options for selecting the item.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

Tree table – Line item
Tree table – Line item

Tree Column

The first colum (tree column) provides the hierarchical structure.

Tree table – Tree column
Tree table – Tree column

Expand/Collapse Button

The expand/collapse button is offered on container nodes to allow the child items of the corresponding container to be shown or hidden.

Tree table – Expand/collapse
Tree table – Expand/collapse

Container Node

A container node is a line item that contains child elements.

Tree table – Container node
Tree table – Container node

Leaf Node

A leaf node is a line item that does not contain child elements.

Tree table – Leave node
Tree table – Leave node

Cell

Each cell provides one data point. It can contain one of the following controls to display the data point: text, label, object status, icon, button, input, date picker, select, combo box, multi-combo box, checkbox, link, currency, rating indicator.

While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

Tree table – Cell
Tree table – Cell

 Tree Cell

A tree cell is a cell inside the tree column. Besides its data point, it provides a collapse/expand button on container nodes, and it indents the different hierarchy levels.

Tree table – Tree cell
Tree table – Tree cell

Column Header Menu

For the tree column, the column header menu can contain the menu item Freeze and a Filter field, in which the user enters free text.
For all other columns, only the free text filter is available.

Tree table – Tree column header menu
Tree table – Tree column header menu

Selection Cells

For multiselection tree tables, the first column contains checkboxes for selecting line items. Besides multiselection, the tree table offers a single-selection mode and also a read-only mode, in which line items are not selectable.

Tree table – Selection cells
Tree table – Selection cells

Select All

For multiselection tree tables, the column header can contain a checkbox above the selection cells for selecting or deselecting all line items.

Tree table – Select all
Tree table – Select all

Scrollbar

The tree table allows horizontal and vertical scrolling. You can add any number of line items to the tree table, which is known as “lazy loading”.

To prevent adverse side effects when scrolling vertically, all line items must have the same height (sap.ui.table.TreeTable, property: rowHeight).

Tree table – Vertical scroll bar
Tree table – Vertical scroll bar

Behavior and Interaction

Selection

The tree provides the following possibilities:

Tree table – No selection
Tree table – No selection
Tree table – Single selection
Tree table – Single selection
Tree table – Multiple selection
Tree table – Multiple selection

Column Header Menu

Sort

The column header menu can provide two sort options (sap.ui.table.Column, properties: sortProperty, showSortMenuEntry):

  • Sort Ascending
  • Sort Descending

The user selects one of these options to sort the corresponding column accordingly (sap.ui.table.Column, properties: sorted, sortOrder, sortProperty).

Sort settings in column header menu
Sort settings in column header menu

Filter

The column header menu can provide a search field for entering free text. If the user enters a term in the input field and triggers the search by pressing Enter, the tree is filtered by the tree column and the corresponding value. If no items match the filter values, the filtered tree table may be empty.

Tree table – Filter
Tree table – Filter

Freeze Columns

The Freeze/Unfreeze option is provided in the column header menu of all columns. Using Freeze on one column freezes all columns from the first one to the selected one.

Tree table–- Freeze
Tree table–- Freeze

Column Handling

Show/Hide Columns

Columns can be shown and hidden. If the tree column is hidden, the following column is the tree column.

Rearrange Columns

The user rearranges columns by dragging and dropping the corresponding column header. The tree column is always the first column and cannot be dragged.

Resize Columns

Columns are resized as follows:

  • Mouse interaction: The user drags the separator line between two columns (sap.ui.table. Column, property: Resizable). Double-clicking the line optimizes the column according to the length of the currently visible data and the label of the column header (sap.ui.table.Column, property: Autoresizable). Note that auto-resizing works only if the cells in this column contain one of the following controls: text, label, link, or input.
  • Touch interaction: The user clicks or taps the column header to reveal two buttons: One to show the column header menu, and one for resizing. The user drags the latter to resize the column.

Cell Content

The tree is traditional in that each cell can contain only one data point in one single line.

Apart from plain read-only text, cells can contain the following:

While it is technically possible to also use other controls, doing so could lead to issues in regards to alignment, condensed mode, screen reader support, and keyboard support.

If you use text, use only single-line text to keep the same row height. Truncate if necessary as this prevents adverse side effects when scrolling vertically (sap.m.Text, property: wrapping, value: false).

Guidelines

Filtering

  • To filter, choose the filter bar instead of the built-in free text filter.
  • Only use the free text filter if the filter bar is too heavy.

Loading Data

To indicate that the table is currently loading items, use the busy state (sap.ui.table.TreeTable, property: busy). Do not show any items or text. As soon as the data has been loaded, remove the busy state and show all items.

Initital Display

Think of the initial expand / collapse state of a tree: If your structure contains many items on the root level, it might make sense to collapse the whole tree in the beginning.

In contrast, if the main items to work with are displayed on a deeper level (e.g. the parent nodes are just some kind of categorization), the tree should be expanded up to the first level where the needed items appear.

Empty Table

Try to avoid empty tables. If necessary, provide instructions on how to fill the tree table with data.

Remove the item count in the table title if there are zero items.

Add Items

Place the add button on the table toolbar. It can be displayed as an icon (+) or text (e.g. ‘Add’ or ‘Create’).

In general new items always appear as the first item of the table (or node.

Columns

Minimize the number of columns. Avoid the need to scroll horizontally in the default delivery. In the first column, show the hierarchical data, which should identify the line item. Choose the name over the ID, but if both are needed, show the name first, then the ID.

The tree table assigns the same width to each column by default. It is recommended that you overwrite this default to provide optimal space for your content (sap.ui.table.Column, property: width).

If you define the column width in pixels or rems, resizing a column affects only the width of this specific column. Reducing the browser window size results in a scrollbar. After resizing a column, a scrollbar appears if the width of the table is not enough to show all columns. If the columns use less space than is available, white space appears on the right side of the last column.

If you define the column width as a percentage, resizing one column affects the width of several or all columns. Text becomes truncated when the browser window size is reduced. This is done to make sure that all columns together fill the space of the table. A scrollbar appears only in case the automatic change of the column widths is not enough to display all columns. To avoid the side effect of undersized columns, a minimum width can be set per column. Please be aware that this minimum width is only taken into account if columns are automatically resized. End users are still able to reduce the column width below the provided minimum. (sap.ui.table.Column, properties: width, minWidth)

If you define the column width as “auto”, the behavior is the same as for “percentage”. In contrast to percentage, “auto” distributes the columns equally.

To decide on how to set the column width (pixel/rem/em vs. percent/auto), keep the following tips in mind:

  • For tables with only 2 to 3 columns, use pixel-based units. This ensures that on wide screens the values in the columns are not spread over the whole screen, which improves readability of line items.
  • For tables with many columns, where a horizontal scrollbar is usually needed, use pixel-based units. This avoids unintended side effects when resizing columns.
  • For all other tables, use whatever fits your case better.

Be cautious with mixing columns with pixel-based and percentage-based widths. While this can be helpful in some cases, it could also cause even more unintended side effects when resizing a column. When using percentage-based widths for one or more columns, think of the possibility to not allow end users to resize columns at all.

Alignment of Cell Content

Align column headers according to their cell content:

  • Texts are left-aligned.
  • Numbers (except for IDs), dates, and times are right-aligned.
  • Single-word status information and icons are generally centered.

In addition, align amounts with currencies to the decimal point. You can do this with the sap.ui.unified.Currency control.

Note that most currencies have two digits after the decimal point, but there are exceptions, for example:

  • The Tunisian dinar has three digits.
  • The Japanese yen has no digits.

In tree tables with mixed currencies, all amounts still have to be aligned to the decimal point.

To enable positive and negative values to be identified more easily, position the minus sign to the right of the number. It is placed in the same position in every row.

For more information, see currency.

Formatting Cell Content

  • Note that there are different locale formats, so show dates, times, and numbers in the format corresponding to the user’s language.
  • If text and an ID are to be shown, show the ID in brackets after the corresponding text.
  • Where possible, show the unit of measurement together with the number within the lines, and not only on the column header.

Tree vs. Table

Trees are more complex than tables due to their hierarchical view. Users tend to have more problems finding items in hierarchical views than in flat lists, except where the hierarchical view is natural. By natural we mean that every child node should be part of only one parent, and this relationship between the child and parent is clear and well known.

Do
Example of an acceptable use of tree tables
Example of an acceptable use of tree tables
Do
A clear parent-child relationship
A clear parent-child relationship

When you use trees, you should choose broad hierarchies over deep hierarchies. Deep hierarchies make finding items more complicated. So try to reduce hierarchical levels where possible, especially if the hierarchy is not natural. Ideally, a tree should have a maximum of four levels, the first two of which should contain the most important items.

Don't
Avoid unnecessary depth in the hierarchy
Avoid unnecessary depth in the hierarchy
Do
Favor breadth over depth in the hierarchy
Favor breadth over depth in the hierarchy

You can use the following methods to reduce hierarchy levels:

  • Avoid single root nodes. A single root node is often used to provide a Select All feature. Since the tree control provides an extra space for a Select All feature, the root node is not usually needed.
  • When you use only two levels, choose a grouped table or grouped ALV over a tree table control. Expand all groups for the default delivery.
  • Container nodes at the top level can usually be replaced by tabs or value pickers.
  • Eliminate unnecessary mid-level containers, for example, by combining redundant ones.
  • Exercise care when using a tree due to its overall complexity. The hierarchical structure of the data does not necessarily mean that a tree control is required.

Design Concepts

The tree table can be used to display large amounts of hierarchical data. Unfortunately, tree tables have a high data density and therefore convey an immediate feeling of complexity. Ideally, tree tables with large amounts of data should only be shown if there is no other option. You should instead try the following:

  • Flatten the data. A list, table, or ALV is still complex, but less so than a tree table.
  • Break down the data into manageable chunks. Allow the user to navigate or drill down between them.
  • Use charts with drilldown functionality until the amount of data is more manageable.

Try to avoid horizontal scrolling in the default delivery.

Examples of Incorrect and Correct Usage

When you use trees:

  • Choose breadth over depth.
  • Emphasize important values. Do not let the user run into a wall of text without guidance. You can use bold text for this.
  • Try to minimize the number of columns, especially if there is a large number of rows.
  • Optimize column width for its initial visible content. Do not automatically adjust column width based on content changes.
Don't
Avoid: The first visible content should not be truncated in the default delivery
Avoid: The first visible content should not be truncated in the default delivery
  • Maintain a fixed layout, except when the user wants to change it.
  • In the default layout, use the tree column for the item name or data that identifies the row. This helps the user to choose between different items.
  • Create a clear and immediately understandable hierarchy. Use clear parent-child relationships. If this is not possible, add a child in different nodes to help the user find the element.
Do
Acceptable: repeat entries to optimize finding items
Acceptable: repeat entries to optimize finding items
  • Avoid showing an empty tree table.
  • Consider persisting the layout settings. When a user reopens the app, show the tree table with the same column sizes, column order, and view settings as last defined by this user.
  • Use the Select All feature only if it makes sense. Note that selecting a lot of data also takes time and might not be appropriate for all use cases. For example, a delete operation on two million database entries might not be very helpful in many cases.

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

Implementation

Range Slider

A range slider is a user interface control that enables the user to select a value range in a predefined numerical interval.

Range slider
Range slider

Usage

Use the range slider if you want to select a value range in a predefined numerical interval. If you want to specify only a single value in 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
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 value range of the slider can be changed when the grips are adjusted via drag and drop. The grips can be moved with or without increments based on the predefined steps. The value range can be changed by clicking or tapping the bar outside of it. The corresponding grip then moves to this new position.

Range Slider - hovered
Range Slider - hovered

Range Slider With Input Fields

The range slider can be used with input fields instead of tooltips.

Range slider with input fields
Range slider with input fields

Moving the Entire Range

The value range can be changed when the progress line is adjusted via drag and drop.

Range slider - Moving the entire range
Range slider - Moving the entire range

Equal Values

The grips of the range slider can be positioned on the same value.

Range slider - equal values
Range slider - 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 step 10, the range slider will have 11 tick marks. The tick marks are responsive. If the distance between 2 tick marks is less than 8px, all tick marks except for the first and last will disappear.

Range slider - with tick marks
Range slider - with tick marks

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 will be sent to the console.
  • The inputsAsTooltips property indicates whether input fields should be 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

Implementation

Harvey Ball Micro Chart

You can use a Harvey Ball chart to visualize a value compared to its total. This is not a pie chart with multiple values or sections, but rather just one value from a total. If you configure thresholds, the semantic color of the value shows a positive, critical, or negative value. You can also use regular chart colors without a semantic meaning.

Different Harvey Ball charts
Different Harvey Ball charts

Usage

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

Responsiveness

See the Micro Chart overview article.

Resources

Elements and Controls

Implementation

Header Toolbar

The header toolbar always appears in the header of the page. One main advantage of the header bar is that this bar is always visible and will not scroll away. It contains actions that are relevant for the entire page.

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

Buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons go into the overflow last.

Usage

Use the header toolbar if:

  • Your page contains several controls, and the actions are valid for the entire page.

Do not use the header toolbar if:

  • You have closing or finalizing actions for the whole page. Place them in the footer toolbar instead.
  • You have actions that belong to a specific UI element. Place them as close as possible to the corresponding object (for example, in a table or chart toolbar).

Responsiveness

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

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

Header Toolbar on Object page – Size S
Header Toolbar on Object page – Size S
Header Toolbar on Object page – Size M
Header Toolbar on Object page – Size M
Header Toolbar on Object page – Size L
Header Toolbar on Object page – Size L

Components

The header toolbar can contain the following components:

  • App-specific actions
  • Generic actions

 

The following actions count as generic:

  • Add
  • Flag and Favorite
  • Share menu
  • Overflow
  • Paging

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.

App-specific icon button in header toolbar
App-specific icon button in header toolbar

Add (Generic)

The Add (item or row) action 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. Note that if you use icon buttons instead of text, the icon appears on the right, next to the text actions.

Add as icon button (+) in full screen mode
Add as icon button (+) in full screen mode

If the app development team wants to use a combination of actions, such as Add, Edit, and Delete, we recommend placing the actions as text buttons. Only by doing so can the buttons be arranged side by side.

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

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

Edit and Delete (Generic)

If you want to perform a global edit action, use the Edit button.

If you want to perform a global delete action, use the Delete button.

Edit and Delete in header toolbar
Edit and Delete in header toolbar

Favorite and Flag (Generic)

Users can mark objects as a favorite or flag objects for quick subsequent retrieval. The user does this by clicking or tapping the relevant generic Favorite or Flag button in the header toolbar. For more information, see flag and favorite.

Favorite action in header toolbar
Favorite action in header toolbar

Share (Generic)

The Share menu allows users to work with content outside the app they are currently using. It can include a variety of actions. All the buttons contain either text only or a combination of an icon and text. The following actions can be used and complemented by each app:

  • Send Email (icon: email  )
  • Discuss in SAP Jam (icon: discussion-2  )
  • Share in SAP Jam (icon: share-2  )
  • Send Message (icon: post  )
  • Save as Tile (icon: add favorite  )
  • Print (icon: print  )
  • Export as Excel (icon: Excel attachment  )
  • Export as PDF (icon: pdf attachment  )
  • Export As…
  • Open In…

If you expect the user to use the Open In… functionality frequently, place it directly in the footer toolbar. This is described in detail in the Open In… section below.

The Share action can appear on the full screen or the details screen, and is never moved into the overflow menu. It is always right-aligned. The overflow starts to the right side of the Share icon.

Possible actions in the Share menu
Possible actions in the Share menu
Share in Header Toolbar
Share in Header Toolbar

Overflow (Generic)

If apps use the overflow toolbar, the overflow is generated automatically. The overflow is activated if there is not enough space for all the actions on the toolbar, or if some actions are considered less important than others. In this case, the app team decides that only certain actions appear in the overflow.

The app team also decides whether some actions are so important that they should never move into the overflow.

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 button, 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

Split-screen layouts have their own overflow menus.

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

Header toolbar on desktop with open overflow
Header toolbar on desktop with open overflow

Paging (Generic)

Use the Paging button if you want to navigate to the previous or next object.

If you are using the Share button, the paging button should be placed to the right of the Share button.

Paging buttons in header toolbar
Paging buttons in header toolbar

Styles

Button styles should be used to help the user, and not for decoration.

They should be defined for actions that a user will primarily use, such as Edit, Create, and Save.

Use either a positive or negative (property: type – accept/reject), or an emphasized (property: type – emphasized) button. Avoid using both styles on one screen.

Exception 1: Message button appears.

Exception 2: Object is marked as flag/favorite.

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

Implementation

Smart Table

The smart table is a wrapper around existing tables, and can be used together with the responsive table, grid table, analytical table, or tree table.

The smart table creates columns automatically based on the underlying OData service plus corresponding annotations. It also adds some generic functionality, such as a toolbar, complex personalization settings, variant management, and export to spreadsheet.

Everything that can be done using the smart table can also be achieved using the responsive table, grid table, analytical table, or tree table directly, but with more development effort. Therefore, the main purpose of the smart table is to reduce development effort. However, this comes at the expense of decreased flexibility.

Usage

Use the smart table if:

  • Data is fed into the table through OData services.
  • You need a simple table with limited flexibility to display its content. In this case, the smart table reduces development effort.
  • You need a table in which some columns provide flexible content. In this case, use the smart table together with a responsive table, and provide app-specific column definitions for these columns.

Do not use the smart table if:

  • You create your own UI coding, whereby the data is not fed through OData services. In this case, use the underlying table control directly.
  • The main use case involves selecting one item from very few items, with no additional details. In this case, a select or combo box might be more suitable.
  • The main use case involves selecting one item from several items, with only a few details per item. In this case, a list might be more suitable. Pay attention to the layout of the list item to provide a pleasant appearance (see, for example, the master list and the feed list item).
  • The table is displayed together with a chart inside a chart container. The smart table is not designed to work inside an existing chart container. In this case, use the underlying table control directly.
  • You need an overview of a large amount of data. In this case, use charts.
  • You just need it for layout reasons. In this case, use a layout container, such as the grid layout, instead.
  • You need read-only or editable field value pairs. In this case, use a form instead. Tables are not optimized for form-like input navigation.

Responsiveness

The responsiveness of the smart table depends on the encapsulated table. The table toolbar uses the overflow mechanism for adapting to the screen width.

Using the responsive table

The smart table offers a generic responsive behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true):

  • For every 10 rem of screen width, one column stays in the tabular layout. All others are moved to the pop-in area. The columns are moved to the pop-in area from right to left, so the column furthest to the right moves to the pop-in first.
  • Exception: The first two columns always stay in the tabular layout. This works best if the smart table uses the whole screen width. It might not work well if the smart table uses far less space.

Using the grid table, analytical table, or tree table

  • The smart table works only on desktop and tablets, but not on smartphones. It supports touch devices, but is not optimized for small screens.
  • If you use a smart table in this configuration, ensure that you implement a fallback solution for small screens. This fallback solution does not need to support all use cases. You could create a fallback by using a responsive table. However, a completely different solution, such as showing charts in a read-only case, might be more suitable.
Size S with responsive table
Size S with responsive table
Size M with responsive table
Size M with responsive table
Size L with responsive table
Size L with responsive table
Size M with grid table
Size M with grid table
Size L with grid table
Size L with grid table

Layout

The title bar contains the title of the smart table, the item count, variant management, and the toolbar itself. All of these elements are optional.
The table area shows the corresponding table (responsive table, grid table, analytical table, or tree table).

Schematic visualization of the smart table
Schematic visualization of the smart table

Components

The title bar consists of a toolbar.

This can be the standard toolbar or a custom toolbar. The standard toolbar can contain a title text with or without item count, variant management, view switch (switching the table to edit mode), an entry point for the P13n dialog, and an Export to Spreadsheet action.

If you require additional functionality, you can use an app-specific toolbar. All toolbar options provided by the smart table can also be added to the app-specific toolbar. (Aggregation: customToolbar)

The table area consists of any of the following tables: responsive table, grid table, analytical table, or tree table.

Standard toolbar with everything enabled
Standard toolbar with everything enabled
Standard toolbar just with title and item count
Standard toolbar just with title and item count

Behavior and Interaction

The behavior is generally inherited from the underlying table, toolbar, variant management, and P13n dialog (see the corresponding articles for details.) Note that the smart table provides limited options and not all settings of the underlying controls are available.

Table Level

Table Type

The smart table can encapsulate the responsive table, grid table, analytical table, or tree table. (sap.ui.comp.smarttable.SmartTable, property: tableType)

Automatic Rendering of the Table

The smart table automatically creates columns and renders all items based on the metadata of the underlying OData service (sap.ui.comp.smarttable.SmartTable, property: smartFilterId).

To be more flexible in the table layout, the smart table also offers app-specific column templates for some or all columns. In this case, app developers must provide the definition for the underlying table and for the corresponding (but not necessarily for all) columns in the XML view. For this, the app development team must provide the column keys of the overridden columns via custom data.

Additional columns can also be added. Columns that are defined in this way retain all the options of the underlying table. This is especially useful with the responsive table, which offers complete flexibility in content design. Any columns that are not defined by the app development team are still rendered automatically by the smart table.

No Data

If there is no data to show, the smart table renders default text. This text can be overwritten by the app development team (aggregation: NoData).

Initially Visible Columns

The smart table enables you to define which columns are initially shown. Here, initially means that these columns are shown when the app is first launched. All other columns are initially hidden (annotation: PresentationVariant/ LineItem, property: initiallyVisibleColumns).

Persistency

End users can show additional columns if table personalization is provided. In this case, column settings are persisted. On consecutive startups, the columns are shown with the same settings as last defined by the user (property: persistenceKey).

Removing Columns

The smart table always shows all columns from the OData model. In some cases, columns needs to be in the model but should not be available on the front end at all. Examples of this include:

  • A column is needed to provide an ID which is used for navigation purposes, but the front end should only display the corresponding text, not the ID.
  • The values of a column are needed to perform calculations, but only the results should be shown on the UI.

In these cases, you can define which columns should not be available at all on the UI. These columns are not shown and are not available in the P13n dialog. You can also do this for columns that are added manually in the XML view (annotation: sap:visible, value:false).

P13n/personalization dialog
P13n/personalization dialog

Filter Settings

The “Show Field as Column” option for newly added filters is switched on by default.

Sorting and Filtering

The smart table allows you to add sort and filter settings for each column. These settings enable the corresponding pages in the P13n dialog. For the grid table, analytical table, and tree table, sorting and filtering are also enabled on the column header. (Annotations: sap:sortable and sap:filterable)

Column header menu of the grid table
Column header menu of the grid table

Smart Table and Smart Filter Bar

The smart table can be linked to a smart filter bar. If linked, filter bar settings are automatically used on the smart table. (sap.ui.comp.smarttable,SmartTable, property:smartFIlterId)

Aggregation

If used with the analytical table, the smart table allows total sums of measure columns to be calculated. The totals are shown in the usual way:

  • As the last row of the analytical table.
  • As the last row of each group if the group is expanded.
  • On the group header of each group if the group is collapsed.

Aggregation settings are not persisted (annotation: sap:aggregation-role, value:measure).

The total count be hidden via the column header menu.

Aggregation entry in column header menu of the grid table
Aggregation entry in column header menu of the grid table

Column Width

A default column width is calculated for each column based on the data displayed in it. Important: end users cannot change the column width in the responsive table (annotations: MaxLength, Precision, Scale).

Column Header

A column header text can be specified for each column (annotation: sap:label).

Persistence

The smart table allows you to persist sort, group, and filter column settings (such as by hidden columns) as well as variants (sap.ui.comp.smarttable.SmartTable, Property:persistenceyKey).

Content

The smart table provides two options to create columns automatically:

  1. The smart table is rendered in either read-only or edit mode. In this case, the smart table renders the controls as described below. This is the default way of rendering content (property: editable)
  2. If users need to switch between read-only and edit mode at runtime, the smart table allows smart fields to be rendered instead. You should use this if the edit button is added to the toolbar of the smart table (aggregation: customData key: useSmartField, property: smartToggle).

For option 1, the following controls are used:

  • To show currency amounts, the smart table allows the amount and the currency code to be displayed in a single cell. For read-only mode, the currency control is used. For edit mode, a single input field is used, and the currency itself is shown next to the input field as non-editable text (annotation: sap:semantics, value: currency-code).
  • To show links that open a quick view, the smart table supports the smart link.
  • To show static text, the smart table uses an input field in edit mode, and a text in read-only mode.
  • To show dates, the smart table uses a date picker in edit mode, and a text in read-only mode (annotation: sap:display-format, value:Date).
  • To show decimal numbers, the smart table uses an input field in edit mode, and a text in read-only mode (Annotations:Precision, Scale).
  • The smart table also provides an object status and object identifier control. For more information, see object display components.
  • Pictures and microcharts, as well as rating indicators and progress bars are available.
Amount formatting
Amount formatting
Link formatting
Link formatting
Date formatting
Date formatting

Value Help

The smart table supports value help in the following ways (annotation: ValueList):

  • Input fields can show a value help button. Triggering this button opens a value help dialog. Within this dialog, you can provide a search field (annotation:ValueList, property: SearchSupported).
  • You can restrict the number of characters for the input field. Use this if no ValueList annotation is provided (annotation:MaxLength).

Toolbar Level

Table Title

The smart table can provide a title for the table within the toolbar (sap.ui.comp.smarttable.SmartTable, Property:header).

Table title
Table title

Item Count

Next to the table title, an item count can be shown (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Table title with item count
Table title with item count

Edit

The table toolbar can contain a button for toggling the table between read-only and edit modes. If smart fields are used, the smart table handles both modes automatically (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).

If used with the responsive table, the edit button also switches the keyboard behavior accordingly.

Edit button
Edit button

View Settings

The table toolbar can contain a button for opening the P13n dialog. This dialog provides extensive sort, group, and filter settings. It also allows columns to be shown, hidden, or rearranged (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Settings button
Settings button

Export to Spreadsheet

If the back end supports the export of data to spreadsheet, the table toolbar can contain a corresponding button. When this button is triggered, the corresponding file is created and the download starts automatically (sap.ui.comp.smarttable.SmartTable, Property:useExportToExcel).

Export to Spreadsheet button
Export to Spreadsheet button

Full Screen Mode

Applications can implement a maximize button to run the table in full screen (Property: showFullScreenButton).

Maximize button
Maximize button

Footer Toolbar Level

Buttons in the footer toolbar can be set to emphasized to give them a brighter appearance.

Guidelines

In general, the guidelines for the underlying table, toolbar, variant management, and P13n dialog also apply to the smart table (see the corresponding articles for details). However, because the smart table does not offer the complete flexibility of the underlying controls, there are certain differences.

Table Type

The responsive table is the standard table for SAP Fiori. Use the responsive table whenever possible. It is the most flexible table in terms of how its content is displayed, it is fully responsive, and it can handle up to 1,000 line items.

If you cannot use the responsive table, consider using the grid table instead. The grid table can handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the grid table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The analytical table is similar to the grid table, but adds several grouping levels and offers total sums on measure columns. The analytical table can also handle a large number of line Items. Compared to the responsive table, however, it is more restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the analytical table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

The tree table is the only table for displaying hierarchical data. Like the grid table, it can handle a large number of line items, although it is restricted content-wise (only certain controls can be used to show the data, and only one control per cell), and it does not run on smartphones. If you use the tree table, you need to provide a fallback solution for smartphones, for example, by using the responsive table.

For more information about the different table controls, see the corresponding articles.

Table Title, Item Count, and Variant Management

Always show the item count together with the table title, unless this is expected to cause performance problems.
If used with the responsive table and if more than 200 items are generally expected, do not show the item count. In this case, the smart table displays a More button to load additional rows. Using the item count together with the More button might lead to confusion (sap.ui.comp.smarttable.SmartTable, Property:showRowCount).

Even if variant management is easy to implement, use it only if it is really needed. The variant management saves the whole page, including filter settings and table layouts.

Empty Tables

Try not to display an empty table. If there is no way around this, provide instructions on how to fill the table with data (aggregatrion: noData).

Columns – Best Practices

Keep the number of initially shown columns to a minimum. Avoid the need to scroll horizontally on a tablet screen size in default delivery (annotation: PresentationVariant/ LineItem).

Keep the number of additional (initially hidden) columns to a minimum. You can use the P13n dialog to show/hide the columns. Select the columns offered in the P13n dialog carefully. Do not just show all columns available in the backend tables (annotation: sap:visible, value:false).

For the grid table, analytical table, and tree table, the column widths are calculated automatically if the corresponding OData annotations are provided (annotations: MaxLength, Precision, Scale).

In contrast, the responsive table uses the same width for all columns.

If used with the responsive table, enable the pop-in behavior (sap.ui.comp.smarttable.SmartTable, property: smartFilterId, value: true).

Show the most important column on the left and the least important on the right. This ensures that the most important columns stay in the tabular layout as long as possible. The most important columns are those that contain the following information:

  • The column that identifies the line item
  • The column that contains the key attribute

(Annotation: PresentationVariant/ LineItem, Property: initiallyVisibleColumns)

Email column in the pop-in area of the responsive table
Email column in the pop-in area of the responsive table

Provide a column header text for each column. Do not truncate the column header text in default delivery (annotation: sap:label).

Column header text
Column header text

Content Alignment and Formatting

The smart table automatically takes care of content alignment and formatting in standard use cases. For this, the OData metadata needs to provide the correct information about the data types, semantics of, and value help for the data.
(Annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values)

Actions

To trigger actions on multiple items, use a mutliselection smart table. Do not offer action triggering on multiple items if the table is expected to have fewer than 10 items in most cases.
While the grid table, analytical table, and tree table are multiselectable by default within the smart table, the responsive table is single-selectable. The selection mode can be changed (XMLView).

The following actions can be shown on the standard toolbar of the smart table:

  • Edit
    Toggles the table between edit and read-only mode. This only works if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, properties:editTogglable, smartToggle, aggregation: customData, key: useSmartField).
  • View Settings
    This button opens the P13n dialog. Note that the P13n dialog is quite complex. Neither the simpler view settings dialog nor the table personalization dialog can be used without the app development team developing the entire view settings handling (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).
  • Export to Spreadsheet
    Only use this option if your end users typically export the data shown in the table in order to work with it in a spreadsheet application. This is usually the case if data is collected from several systems and analyzed in the spreadsheet application. This is not usually the case for worklists, attachment lists, lists with only a few items, shopping carts, or data that does not need to be analyzed. This option is only available if the corresponding back end supports exporting to spreadsheet (sap.ui.comp.smarttable.SmartTable, property: useExportToExcel).

If additional actions are needed, use a custom toolbar for the table. The smart table can also add integrated functionality such as a table title, item count, variant management, edit and view settings, and export to spreadsheet to the custom toolbar (aggregation: customToolbar).

For navigation to line item details:

  • If used with the responsive table, use the navigation mode of the responsive table.
  • If used with the grid table, analytical table, or tree table, use a link for the attribute that identifies the row. The user can click this link to trigger the navigation.

Clicking a table row can trigger drill-in navigation to a deeper level of the object, as well as cross-navigation to another SAP Fiori app or even to another system.

Inline Actions

Actions that belong to single items can be placed within the row. They can be displayed as text or icons. Make sure the icon communicates the function clearly enough. Otherwise, use a textual button.

Editable Content

The smart table can be editable or read-only (sap.ui.comp.smarttable.SmartTable, property: editable).

The smart table selects the corresponding editable controls automatically based on the data type, semantic annotations, and value list annotations (annotations such as: sap:semantics, value: currency-code, edm types, Annotation: sap:display-format, value:Date, Annotation:Precision, Annotation: Scale, Annotation: ValueList, Annotation: ValueList:semantics, value:fixed-values).

If an edit mode is needed, the controls are automatically switched from read-only controls (such as text) to editable controls (such as input field or date picker) if smart fields are used inside the smart table (sap.ui.comp.smarttable.SmartTable, Property:editTogglable, smartToggle, aggregation: customData, key: useSmartField). The keyboard behavior is switched accordingly, if this is used together with the responsive table.

Only use this if you need to toggle between both modes. In any other case, show only the mode you need (read-only or edit), but do not offer the switch.

View Settings: Sort, Filter, Group, and Column Settings

If view settings are enabled on the smart table, a settings button is available on the table toolbar. This button opens the P13n dialog. Neither the simpler view settings dialog nor table personalization dialog can be used without extra effort (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

The P13n dialog always enables the user to show, hide, and rearrange columns. Alternatively, it can contain settings for sorting, grouping, and/or filtering (annotations: sap:sortable, sap:filterable)

If the smart table uses the grid table, analytical table, or tree table, sort, filter, and group settings are also available in the column header menu.

Offer view settings only if they are really needed. For example, these settings do not make sense if the table contains only a few items and just a few columns.

Note that the P13n dialog is quite complex. It is ideal for tables with a vast number of items, but is quite cumbersome for handling just a few hundred items. Therefore, show only the settings (sort, group, filter) you really need. For example, do not offer grouping if it does not support your use case well.

If filtering is a main use case, do not offer filtering in the P13n dialog. Use the filter bar instead (annotation: sap:filterable)

Be persistent: When the app is reopened, the smart table is shown with the same view settings as last defined by the user (sap.ui.comp.smarttable.SmartTable, property: persistenceKey).

Sort

The current sort state is displayed as follows:

In default delivery, sort items in a meaningful order by the row-identifying column (usually the first column in default delivery). For example, use an alphabetical order for text, a numeric order for numbers, and a chronological order for dates (annotations: sap:sortable, PresentationVariant – SortOrder).

Filter

The current filter state is displayed as follows:

Group

Group headers display the current group state and are shown automatically. The following text should be shown on the group header:

[Label of the grouped column]: [Grouping value]
This can be done by the smart table, but only if the raw data from the model can be used. In other cases, app development teams must format the group header text. For example, the raw data carries IDs, while the table displays the corresponding names, which are provided by another data source. In this case, app developers must provide the formatting for the group header texts.

Within the responsive table, the grouped column keeps its visibility to reduce confusion after the group settings have been changed. If visible, it stays in the tabular layout even if grouped.

If used with the analytical table, grouping is not offered on measures. Therefore, you can have aggregations or grouping for a specific column.

Reasonable grouping can be offered by default via the property GroupBy.

Responsive table grouped by country
Responsive table grouped by country

Aggregate

If used with the analytical table, aggregation settings can be provided on measure columns. These settings are only available in the column header menu.
To display the current aggregation state, the total sum of the corresponding column is shown at the bottom of the table.
If items are grouped, an intermediate sum is shown per group:

  • At the bottom of each group if the group is expanded.
  • In the group header if the group is collapsed.

Aggregations are only available on measures, but not on objects or attributes. If aggregation is enabled for a column, this column cannot be grouped.

Avoid aggregations on the first three columns for the default delivery. When grouping is used together with aggregations, collapsing a group shows the aggregation on the group header. This conflicts with the group name.

Where appropriate, offer reasonable aggregation by default (annotation: sap:aggregation-role, value: measure).

Column Settings

Only offer column settings if you need more columns than a tablet screen can display at a time (usually more than five).

If sorting, grouping, and/or filtering are needed, column settings must also be shown (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Add, Remove, Rearrange Columns

Use the P13n dialog to add, remove, and rearrange columns.

When used with the grid table, analytical table, or tree table, columns can also be rearranged by dragging and dropping the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Resize Columns

When used with the grid table, analytical table, or tree table, columns can be resized on the column header (sap.ui.comp.smarttable.SmartTable, Property:useTablePersonalisation).

Freeze Columns

When used with the grid table, analytical table, or tree table, app developers must manually add the options for freezing columns to the column header menu if necessary. They can do this by declaring the corresponding table inside the smart table in the XML view, and by using the corresponding settings on this inner table.

Selecting Freeze on a column freezes all columns from the first one to the one on which Freeze is selected. The menu entry on this column changes from Freeze to Unfreeze.

Properties

The following properties are available on sap.ui.comp.smarttable.SmartTable:

  • The property: ignoreFields defines the columns that are not available on the UI – neither in the initial visible columns nor in the P13n dialog.
  • The property: requestAtLeastFields can be used for requesting additional technical columns.
  • The property: ignoreFromPersonalization removes columns from the P13n dialog.
  • The property: toolbarStyleClass is deprecated. Do not use it.
  • The property: enableCustomFilter allows the filter menu item in the column header menu to be exchanged.
  • The property: useOnlyOneSolidToolbar is deprecated. Do not use it.
  • The property: currentVariantId defines the currently used variant.
  • The property: enableAutoBinding fetches the data automatically as soon as the corresponding OData model is initialized and the smart table is created.
  • The property: tableBindingPath defines the path from which the data is fetched.
  • The property: smartToggle influences the way on which controls are displayed in the smart table if smart fields are used.

The following aggregations are available:

  • The aggregation: semanticObjectController is used to customize smart links inside the smart table.
  • The aggregation: noData provides a text in case the table contains no line items. For example, this can be the case if the table is filtered. The text should provide context-specific instructions on how to get data into the table.

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

Implementation

Rating Indicator

The rating indicator can be used to rate content or to indicate a rating. It enables users to rate an item on a numeric scale. The most popular scale is 1 (lowest) to 5 (highest).

Rating indicator
Rating indicator

Responsiveness

The rating indicator runs on all form factors and therefore works on all devices. It is embedded in a container and thus behaves as part of it.

Rating indicator as part of the form – Size S (for example, smartphone)
Rating indicator as part of the form – Size S (for example, smartphone)
Rating indicator as part of the form – Sizes M and L (for example, tablet and desktop)
Rating indicator as part of the form – Sizes M and L (for example, tablet and desktop)

Layout

Context

Use the rating indicator in forms, tables, or in a dialog box.

Rating indicator as part of a form
Rating indicator as part of a form
Rating Indicator as part of a table
Rating Indicator as part of a table
Rating indicator as part of a dialog box
Rating indicator as part of a dialog box

Popover with Details

In collaborative rating scenarios, the rating indicator shows an average of all ratings. You may show the sum of ratings in brackets behind the rating indicator as a text or link. You may also add a popover that shows the detailed ratings for the average of all ratings.

Details for rating in popover
Details for rating in popover

Behavior and Interaction

Hover

When the user hovers over the rating indicator, a different icon or image is shown (property: iconHovered). This is an orange star by default.

Select

If enabled for rating, the rating that the user previously selected is shown. When the user performs a rating, an event is triggered.

Types

There are two types of rating indicators:

  • Interactive – used for rating an item
  • Disabled

As the non-interactive state (rating result preview) is not available currently, use the disabled state instead.

Types of rating indicator: Interactive and disabled
Types of rating indicator: Interactive and disabled

Properties

Rating Symbols

You can also specify the URLs for the images or icons that are used as rating symbols (property: iconUnselected). Five star symbols are used by default. Although you can use other images or icons, we generally recommend that you use the star symbol. You can only choose 1 symbol for the unselected and 1 for the hovered state.

Number of Rating Symbols

You can specify the number of rating symbols (property: maxValue). We recommend using a maximum of 7 symbols, although 5 symbols are preferred.

Float Values

Float values can be visualized as a half or full star (property: visualMode). The rating indicator can display a half star only in preview mode (disabled).

Size of Rating Symbols

The recommended sizes of the image or icon to be displayed are:

  • Large: 2 rem (32 px)
  • Normal: 1.375 rem (22 px) – default
  • Small: 1 rem (16 px)
  • XS: 0.75rem (12px)
Possible sizes of rating indicator: Size L, size M, size S, and size XS
Possible sizes of rating indicator: Size L, size M, size S, and size XS

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

Implementation

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
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 a mouse and keyboard operated device.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

  • If the slider is editable, the hand cursor appears when the grip is hovered.
  • The slider can be changed when the grip is adjusted via drag and drop.
  • The grip can be moved with or without increments based on the predefined steps.
  • The slider can be changed by clicking or tapping the bar. The grip then moves to this new position.
Changing the value
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 will be displayed.

Slider with text fields
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 input fields

Slider with Tick Marks

You can apply tick marks to the slider. The tick marks are related to the step property. The tick marks are responsive. If the distance between 2 tick marks is less than 8px, all tick marks except for the first and last will disappear.

Slider with tick marks
Slider with tick marks

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 without progress bar
Slider with 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

Implementation

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
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 a mouse and keyboard operated device.

Types

Only a horizontal slider is available.

Behavior and Interaction

Changing the Value

  • If the slider is editable, the hand cursor appears when the grip is hovered.
  • The slider can be changed when the grip is adjusted via drag and drop.
  • The grip can be moved with or without increments based on the predefined steps.
  • The slider can be changed by clicking or tapping the bar. The grip then moves to this new position.
Changing the value
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 will be displayed.

Slider with text fields
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 input fields

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 without progress bar
Slider with 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

Implementation

Upload Collection

The upload collection control allows users to upload single or multiple files from a device (desktop, tablet, or phone) to the SAP Fiori app. Typically, uploaded files appear in an Attachments tab. However, files can also be displayed elsewhere.

Information
The upload collection replaces the deprecated sap.ca.ui.FileUpload control. Please refrain from using the old CA control.

Usage

Use the upload collection control if:

  • You want to show a list of uploaded files that can be modified.
  • You want to allow users to add or remove files, and to change the file names.
  • You are still using the old sap.ca.ui.FileUpload control.

Do not use the upload collection control if:

Responsiveness

The upload collection control supports small, medium, and large containers.

Upload collection – Size S
Upload collection – Size S
Upload collection – Size M
Upload collection – Size M
Upload collection – Size L/XL
Upload collection – Size L/XL

Layout

The toolbar at the top of the upload collection control contains an Attachments header with a counter on the left, and an Add button ( ) for adding new items on the right. You can overwrite both the default text Attachments and the counter (property: numberOfAttachmentsText).

Files are listed vertically. Each item has a Rename ( ) and a Remove ( ) button.

While most file types have generic icons (for example documents, spreadsheets, or presentations), image files have a small thumbnail preview.

Layout – Items
Layout – Items

Attributes and Statuses

You can display additional attributes and statuses below the file name. Attributes can include the name of the person who uploaded the file, the upload date, the version number, file size, and so on.

App developers can also set individual statuses. These statuses usually refer to an object’s state in a workflow (such as Approved or Overdue).

If multiple attributes or statuses are displayed, they are separated by a bullet.

Layout – Attributes and statuses
Layout – Attributes and statuses

Technical Statuses

In contrast to the statuses mentioned above, technical statuses are not bound to a workflow or business process. Their main use is to show the current editing status of an object (Draft, Locked, Unsaved Changes). For further uses and more details see the object display components and draft handling articles.

Layout – Technical statuses
Layout – Technical statuses

Types

The upload collection control offers two different modes: UploadCollection and UploadCollectionForPendingUpload.

The classic upload collection allows users to upload single or multiple files directly to the app, where these files are displayed as a list.

In contrast, the upload collection for pending upload requires the user to first add multiple files to a list (usually presented in a dialog) and then explicitly trigger the upload for the entire list.

When the dialog with the list is confirmed, the user returns to the app screen with the upload collection set to busy until the upload is finished.

Behavior and Interaction

Uploading Files

As long as no files have been added to the upload collection, applications need to show a mock-entry that provides users with a hint on how to upload their files.

Interaction – Upload (1)
Interaction – Upload (1)

The Add button ( ) triggers a native operating system dialog that allows users to select the files they want to upload. You can decide whether the dialogs should allow users to select multiple items, or only one item.

Interaction – Upload (2)
Interaction – Upload (2)

Once the files have been selected and the dialog closes, the uploading progress is shown in the list.

Users can cancel individual uploads by pressing the Remove  button provided on each item.

Interaction – Upload (3)
Interaction – Upload (3)

Depending on the use case, the Add button (  ) can be either disabled or hidden.
If a user cannot upload any files at all, the button should be hidden completely.
If a user is only temporarily unable to upload files (for example, due to the server connection), the button should only be disabled to indicate that this state is temporary.

Opening Files

The user can click or tap the icons or thumbnails in front of the attachment. Opening files is handled differently depending on the operating system.

On a desktop device, clicking the file name or icon of a file opens the respective program that has been assigned to this file type. Mobile devices usually open a dialog in which the user can select an app that supports this file type.

Renaming Files

The rename function works identically on desktop and mobile devices.

The user clicks or taps the Rename (  ) button.

The file name becomes an input field in which the existing name is highlighted. At the same time, the Rename  (  ) and Remove  buttons are replaced by two options: OK and Cancel.

When the user starts typing, the highlighted text is overwritten. Alternatively, the user can use the mouse or keyboard to change the selected text.

There are three ways in which to validate the new file name:

  • The user clicks or taps somewhere outside the input field to change the focus.
  • The user clicks OK.
  • The user presses ENTER.
  • Upload Collection - Interaction - Rename (1)
  • Upload Collection - Interaction - Rename (2)
  • Upload Collection - Interaction - Rename (3)
  • Upload Collection - Interaction - Rename (4)
  • Upload Collection - Interaction - Rename (0)

Editing Files

If users need to edit more than just the name of uploaded files, applications can implement an edit dialog with all the elements that can be changed by the user.

The image shows an example of how to structure such a dialog. The fields depend entirely on the use case and can be freely determined by each application.

Further details about editing parts of an object in a dialog can be found in the article manage objects – parts of an object. If multiple files need to be edited simultaneously, make sure to follow the guidelines for mass editing.

Interaction – Example of edit dialog
Interaction – Example of edit dialog

Deleting Files

The delete function works identically on desktop and mobile devices.

As soon as the user clicks or taps the Remove  button on a file, a dialog appears asking the user to confirm the deletion of the respective file.

The file name has to be specified in the dialog. Delete confirms the deletion and the file is removed from the list. Cancel aborts the process, closes the dialog, and brings the user back to the file list without making any changes.

Interaction – Delete
Interaction – Delete

Clickable Attributes

Object attributes can be made clickable. This can be very helpful to provide users with a direct way to access certain information such as a person’s profile, contact data, or the version history of a file.

Examples:

Uploaded By: John Miller

Last Edited By: Donna Moore

Version 1.1

Do not use more than two or three linked attributes per item. Excessive use of clickable attributes will overload the UI with interactive elements and have a negative impact on usability.

Information
If your attribute is a label or value pair, please notice that currently both label and value are linked (instead of just the value). We plan to separate them into a read-only label and clickable value.

Sorting and Filtering

Applications can enable sorting and filtering by placing the respective buttons next to the Add (  ) button. If both functions are provided separately, place Sort (  ) first, followed by Filter (  ). Each button should trigger the respective popover or dialog.

It is also possible to use the view settings dialog to handle both sorting and filtering in the same step. If you do this, use a combined button named Sort and Filter.

Interaction – Sort and Filter (1)
Interaction – Sort and Filter (1)

If a Filter is Set

Keep in mind to show the info bar if a filter is set. The sorting criteria should not be displayed in the info bar.

Clicking the info bar should bring up…
…the filter dialog if sorting and filtering are provided via separate buttons.
…the view settings dialog if only one Sort and Filter button is used.

Optionally, a button can be provided on the right hand side of the info bar to remove all filters.

Interaction – Sort and Filter (2)
Interaction – Sort and Filter (2)

Custom and Bulk Actions

App developers can introduce their own actions and apply an action to multiple objects (bulk actions).

Place both custom and bulk actions in the toolbar of the upload collection control. For the order of the actions, apply the same rules as for other toolbars.

If you want to use custom or bulk actions, you must use multiple selection (property: mode = MultiSelect). This mode removes the actions from each item. Instead, offer all necessary actions in the toolbar.

Interaction – Multi selection
Interaction – Multi selection

Uploading a New Version

With SAPUI5 version 1.38 and higher, the old version of an upload collection will be automatically replaced when the user uploads a newer version. This change no longer requires the user to delete the old version manually.

To upload a new version, the user needs to select a file and click Upload New Version. This button needs to be provided by the application as a custom action (see previous section). The following dialog (identical to standard uploading procedure) allows the user to pick a new file to replace the old one.

Developer Hint
The parameter UploadCollectionItem can be used to update a file with a newer version. The old version will be removed from the list automatically while the new version is uploaded. For more information, visit UI5 Explored.

Handling Duplicates

Some applications may allow duplicate files and file names. This section covers steps to prevent duplicates.

Duplicate File Name During Renaming

In this example, there are two different image files: Product Picture – Front and Product Picture – Back.

Interaction – Validation for renaming (1)
Interaction – Validation for renaming (1)
Interaction – Validation for renaming (2)
Interaction – Validation for renaming (2)

The user types in a name that is identical to one that already exists.

Interaction – Validation for renaming (3)
Interaction – Validation for renaming (3)

When the user clicks OK or tries to remove the focus from the input field, the field is highlighted (semantic color: error).

Interaction – Validation for renaming (4)
Interaction – Validation for renaming (4)

Placing the focus back on the field shows the error message (form field validation).

Interaction – Validation for renaming (5)
Interaction – Validation for renaming (5)

Duplicate Files During Upload

Information
Duplicate files are not recognized by the upload control. If needed, this feature must be implemented manually.

If a duplicate is recognized during the upload process, a dialog appears that allows the user to do one of the following:

1) This text explains the current conflict (no actions possible).

2) With Upload and replace, the current file is replaced with the newly updated one.

3) With Upload and rename automatically, the current file is kept and an incrementally increasing number is added to the newly uploaded file, such as “Technical Specs_2”.

4) With Skip this file, the file is not uploaded and the current file is kept instead.

5) If Do this for all n conflicts is checked, the selected action is applied to all remaining conflicts.

6) The OK button confirms selected action(s).

7) The Cancel button cancels the entire upload process.

Interaction – Upload duplicate – Details
Interaction – Upload duplicate – Details

Styles

The showSeparators property allows you to display dividers between each item. The default value is All, meaning that all dividers are shown. We recommend that you only turn off the separators if you expect to have just a few items since they can help to maintain a better overview in long lists.

Styles – Separators (default)
Styles – Separators (default)
Styles – No separators
Styles – No separators

Guidelines

When to Show/Deactivate/Hide Actions

Apps can control the visibility and the active state for all actions at item level. This applies to the Edit and Delete buttons.

The properties are as follows:

  • VisibleEdit
  • VisibleDelete
  • EnableEdit
  • EnableDelete

All the properties are set to true by default.

If users are not allowed to edit uploaded files, all the Edit buttons should be set to invisible. The same applies to the Delete function.

Identical actions should be placed directly beneath one another.

Do not leave buttons enabled, only to show an error message informing the user that the function is not available.

Identical actions should always appear beneath one another.

Do
Show identical actions beneath each other
Show identical actions beneath each other

If users are not allowed to use a certain function, these buttons should not be shown at all.

Do
Hide functions if the user doesn't have authorization
Hide functions if the user doesn't have authorization

If certain actions are unavailable in some cases, such as for files from other users, we recommended that you disable these actions.

Do
Disable functions not available for a specific file
Disable functions not available for a specific file

Do not disable all actions. If users are not allowed to use a certain action, these buttons should not be shown at all.

Don't
Don't disable all actions
Don't disable all actions

Identical actions should be placed directly beneath one another. In the example opposite, the Remove buttons on the lower two items should be visible but disabled.

Don't
Do not position the same actions differently
Do not position the same actions differently
Information
If you want users to be able to upload only specific file types, we recommend doing this via mime types.
You should also inform users on the UI about the file types they are allowed to upload.

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

Implementation

Timeline

The timeline control shows entries (such as objects, events, or posts) in chronological order.

A common use case is to provide information about changes to an object, or events related to an object. These entries can be generated by the system (for example, value XY changed from A to B), or added manually. The latest entry is always on top.

There are two distinct variants of the timeline: basic and social. The basic timeline is read-only, while the social timeline offers a high level of interaction and collaboration, and is integrated within SAP Jam.

Developer Hint
Information stemming from SAPUI5 SDK: Starting with version 1.34, use the group feed component (sap.collaboration.components.feed.Component) and business object mode (sap.collaboration.FeedType.BusinessObjectGroups) for new integrations and existing implementations running on versions 1.32 and up. Note that the group feed component does not display any updates related to the business object from the backend system (system updates).

Usage

The timeline does not have a fixed location on the UI. Where you place it strongly depends on your use case.

For example:

  • If the timeline is closely related to the content and needs to be seen in parallel, you can use the dynamic side content floorplan.
  • If the timeline contains only secondary information, or only needs to be accessed occasionally, you can embed it in a tab.
  • If you are using the object page floorplan, you can use the horizontal layout to integrate the timeline (see Orientation in the Styles section below).

These are just some of the ways you can position the timeline on a page.

Use the basic timeline if:

  • You want to display read-only content, such as an object history.
  • You do not require social interaction (for example, replies).
  • Your customers do not use SAP Jam.
  • You only expect a long list of posts triggered by the system.

Do not use the timeline if:

  • You expect only a few entries. In this case, you should use a feed by combining the two controls “FeedInput” and “FeedListItem”.
  • You want to provide a way to upload files. Use the upload collection instead. You can still use the timeline to show automated updates about the user’s uploads.

Use the social timeline if:

  • You want users to be able to create their own posts.
  • You need social interaction, such as replies.
  • You expect a long list of posts triggered by users or the system.

Responsiveness

The timeline control is fully responsive and works well with multiple screen sizes.

Timeline – Size S
Timeline – Size S
Timeline – Size M
Timeline – Size M
Timeline – Size L
Timeline – Size L

Layout

The timeline control consists of:

  • A header (optional)
  • A chronological axis
  • Posts/entries

 

The following features can be used optionally:

  • Filter
  • Group
  • Add entries

 

Header

The title describes the content displayed along the timeline axis.

 

Axis

Along the axis, the entries are arranged chronologically. The distance does not correspond to the time between each occurrence.

You can use a vertical or horizontal axis. The timeline can be scrolled along its axis.

By default, the latest entries appear on top. Replies are sorted the other way round.

 

Post (Entry /Feed Update)

Posts can be generated by the system (for example, “Object ABC changed by Mr. X”), or entered manually. The entry includes information about who changed what, and when. Typically, posts in the timeline consist of four sections:

  1. A node
    Using icons on a node is optional. Use icons for either ALL or NONE of the posts.
  1. A header section, which can contain:
  1. An (expandable) content section, which can contain:
  • Text(s) and/or link(s)
  • Structured or unstructured information
  • Images
  1. An optional social section, which can contain some or all of the social features offered by SAP Jam (such as Reply, Like, Bookmark, or Share)

Note: If a section is not used, it should not take up any space within the bubble.

Timeline – Layout
Timeline – Layout

Examples for different visualizations:

Timeline – Layout examples
Timeline – Layout examples

Examples for different visualizations:

Posts can originate from three sources:

  • Manual post: A person actively posts to the timeline (or to another place that supplies updates to the timeline).

Example:
Julie Armstrong: Hey @John Miller. Can you give me an update?

  • Post triggered by user action: The post is triggered by something a person does (such as creating a poll in SAP Jam, adding a document to a group, or uploading an attachment).

Examples:

Julie Armstrong created a poll.
(Followed by a preview of the poll)

John Miller posted the document Sales-Revenue_Q4.xls
(Followed by a preview of the document, if available)

Donna Moore wrote a blog post
(Followed by a preview of the blog post)

Julie Armstrong added the picture our_team.jpg
(Followed by a preview of the image)

  • Post triggered by a technical source: Posts can also originate from a purely technical source (for example, if a threshold has been exceeded, or a deadline has been reached).

Examples:

Boiler BB-258/80 has exceeded its maximum temperature.

Server DS209 is running out of space.

Order #052690 is overdue.

Information
Notes vs. Posts: 

Notes are not the same as timeline posts. They must be kept separate and be visualized differently. Like attachments, users create notes in the context of a business object, typically within a Notes tab.

In the context of a business object, notes have to be seen in the same category as attachments.

The difference is even more apparent if you compare posts to complex notes created with a rich text editor. These notes are fundamentally different from timeline posts.

To show notes on the timeline, trigger a feed post with a teaser text. For example, “Julie Armstrong added a new note: Lorem ipsum…”.

Types

Two types of timeline are available:

  • The basic timeline is read-only without social content.
  • The social timeline allows social user interaction.

Basic Timeline

(Available for all apps without SAP Jam integration)

The basic timeline is read-only. There are no user posts, replies, likes, shares, social profile, or other social features. Only system-triggered posts appear on the timeline. User actions within the app (such as creating notes and attachments, or making calls) are reflected in the timeline automatically.

The image below shows a post in the basic timeline. The image on the right shows an example of a basic timeline.

Basic timeline – Post
Basic timeline – Post
Basic timeline
Basic timeline

Social Timeline

(Available for apps with SAP Jam integration)

With SAP Jam, all social features are enabled. Users can post updates, reply, like, and share. Both user-triggered and system-triggered posts appear on the timeline.

The image below shows a post in the social timeline. The image on the right-hand side shows an example of a social timeline.

Types – Social timeline – Post
Types – Social timeline – Post
Types – Social timeline
Types – Social timeline

Behavior and Interaction

Adding a Post

In the social timeline, users can add new posts by clicking the plus ( ) icon on top of the control.

Clicking the plus (  ) icon opens a popover with the focus set inside the text area so the user can immediately start typing.

Post sends the user’s text, which then appears in the timeline. However, the button stays inactive until the user has typed something to prevent empty posts.

Users can also add @mentions (references) to other users or business objects. Read further details below in the @Mention section.

Interaction – Post
Interaction – Post

Replying to a Post

Next to the Post functionality, Reply is probably the most basic and most essential social feature. It enables communication at item level, which is the main way in which it differs from the feed controls. With feed controls (FeedInput and FeedListItem), new entries are always added to the top of the list; there are no in-line replies in the feed. The timeline, however, allows users to reply directly to a specific entry. The number of replies is shown in the reply link, such as Replies (5).

The user clicks or taps the respective link to trigger a popover that shows all previous replies, as well as a text area that allows the user to post a personal reply.

Interaction – Reply
Interaction – Reply

@Mention

This feature is well known from multiple social networks. Like all social features, it is only available in the social timeline, where it allows users to add a reference to another person or a business object. A ‘mentioned’ person usually receives a notification about the respective post.

The @mention feature is available in all areas that allow the user to post something:

Due to technical restrictions, this feature cannot be used on smartphones for the time being.

Interaction – @Mention
Interaction – @Mention

Users trigger the feature by typing the @ sign, or by clicking or tapping the @ button provided in the footer. The button shows users who are not familiar with this feature how to use it.

The following step-by-step walk-through concentrates on the core functionality, and therefore omits the surrounding controls.

Interaction – @Mention (1)
Interaction – @Mention (1)

As soon as a user types the ‘@’ character, he or she is prompted to enter a person’s name or email address.

Interaction – @Mention (2)
Interaction – @Mention (2)

As the user continues to type, a suggestion list is shown.

Interaction – @Mention (3)
Interaction – @Mention (3)

This suggestion list is gradually reduced to only include items that match the user’s input. If the user clicks on the suggestion or finishes typing the name of an existing person, the @mention is created.

(Due to technical restrictions, @mentions cannot be visually highlighted to indicate a successful match currently. )

Search

Always offer a search with the timeline because it may contain a vast number of entries. A search helps users to find what they are looking for without having to scroll through all the posts and updates.

Initially, the search field is closed and only visualized with a search icon.

Clicking on the icon opens…

… the search field with the focus in the field so the user can start to type immediately.

  • Interaction - Search (1)
  • Interaction - Search (2)
  • Interaction - Search (3)

Filter (Optional)

For timelines with several entry types, it makes sense to enable filtering. You can let users filter the timeline by entry type and by other useful attributes (such as bookmarked for bookmarked items).

The filter is triggered with the respective icon in the toolbar.

Timeline interaction – Filter
Timeline interaction – Filter

Depending on the complexity of the timeline, you can offer different kinds of filter dialog:

  • Single selection
Timeline interaction – Filter with single selection
Timeline interaction – Filter with single selection
  • Multi-selection
Timeline interaction – Filter with multi selection
Timeline interaction – Filter with multi selection
Multi-faceted filter
To implement this combination of feed source and filter, use the view settings dialog (sap.m.ViewSettingsDialog).
Interaction – Filter with ViewSettingsDialog
Interaction – Filter with ViewSettingsDialog

If a filter is set, inform the user in the info bar.

Timeline interaction – Set filter
Timeline interaction – Set filter

Show More

After a certain number of timeline entries, a Show More button can be displayed at the bottom of the list to load additional posts.

Depending on the use case and the performance, each app team must decide for itself how many entries should be shown before the Show More button appears.

When the user clicks or taps Show More, a predefined number of additional posts is loaded. The relative position of the timeline must not change, so the same posts are visible in the same screen position after the additional entries have been loaded.

Behavior – Show More
Behavior – Show More

Grouping

The timeline allows applications to group posts by certain criteria, such as by year. Groups can be expanded and collapsed in order to get a better overview.

The following example shows a collapsed group (Posts from 2016) and an expanded group (Posts from 2015).

Interaction – Grouping
Interaction – Grouping

Custom Actions

App developers can introduce custom actions that can be performed on a timeline post. These actions should be kept to an absolute minimum since they will appear in the limited space next to the social actions (see point 4 in the Layout section above).

In the example opposite, the custom actions Edit (1) and Delete (2) have been added to the post.

Behavior – Custom actions Edit and Delete
Behavior – Custom actions Edit and Delete

In this next example, the custom action Download (3) enables the user to quickly download an attachment directly from the post.

Behavior – Custom action Download
Behavior – Custom action Download

Refresh

Instead of showing new posts as soon as they arrive (which would disrupt the user’s reading), the timeline offers a very subtle way of notifying users about new posts.

App developers can place a message strip directly below the toolbar to show how many new posts can be retrieved from the backend.

Behavior – Refresh
Behavior – Refresh

The message strip works seamlessly together with the timeline’s filter.

Behavior – Refresh and Filter
Behavior – Refresh and Filter

Styles

There are various layout options. When you choose the layout, consider the type of content and the screen real estate available for displaying the control.

 

Orientation

  • Vertical
    Use the vertical timeline for narrow containers or on smartphones (in portrait mode).
Styles – Vertical with icons
Styles – Vertical with icons
Styles – Vertical without icons
Styles – Vertical without icons
  • Horizontal
    You can use the horizontal timeline on wide screens, the object page, or even on smartphones in landscape mode.

You can display both the vertical and horizontal timelines with or without icons.

Styles – Horizontal with icons
Styles – Horizontal with icons

Colors

You can use colors to highlight entries in the timeline and indicate semantic meanings (for example, to indicate the status or urgency of an entry).
Styles – Timeline with icons and semantic colors
Styles – Timeline with icons and semantic colors

Guidelines

  • In narrow containers, use the vertical orientation.
  • In wide containers with little height, such as on the object page, use the horizontal orientation.
  • Only use the speech bubble icon for posts entered manually by users:  
    CSS name: icon-post
    HTML Unicode: & # xe 0 a b ; (remove the spaces)
  • Do not use colors for decoration. Colors are to be used for semantic meaning only (such as for warnings or errors).

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

Implementation

Popover

The popover displays additional information for an object in a compact way and without leaving the page. The popover can contain various UI elements such as fields, tables, images, and charts. It can also include actions in the footer.

Note: The quick view is similar to a popover, but has a predefined structure, a fixed set of UI elements, and automatic UI rendering. Check first whether the quick view is appropriate for your use case. For more information, see quick view.

Usage

Use a popover if:

  • You need to define your own structure.
  • You want to show UI elements that are not available with the quick view.

Do not use a popover if:

  • The quick view is more appropriate for your use case.
  • The objects are in a master list (in this case, the details are shown in the details area).

Responsiveness

The popover can be used in the following ways:

  • Responsive and adaptive: sap.m.ResponsivePopover
    Shows a dialog on smartphones (to be closed with an X) and a popover on a tablet or desktop.
  • Non-responsive: sap.m.Popover
    Always shows a popover. Only use a non-responsive popover if it has very little content. On smartphones, the popover should not use more than a third of the phone’s real estate.

Layout

Structure of Popover

The header and footer are generally optional. The other elements are as follows:

Back (1) – optional
Needs to be implemented if the user can trigger further popovers. Always show popovers in place. Never place them on top of each other.

Title (2)
We recommend that you show an app-specific title for accessibility reasons. If you do not show a title, use the invisible text control (sap.ui.core.InvisibleText) to set a text for screen reader support.

Close function (3)
This feature closes the dialog. It is available for smartphones only and is set automatically (sap.m.ResponsivePopover).

Content (4)
Ensure that the content has a basic design and shows only the most important information. We recommend the following:

  • Use no more than two groups.
  • Limit the total number of fields to eight.
  • Use single-column tables.
  • Use micro charts.

Actions (5) – optional

Popover – General structure
Popover – General structure
Popover – Example
Popover – Example

Behavior and Interaction

Opening a Popover

The user opens a popover by clicking or tapping an object represented by a text link or an icon. To improve accessibility, we recommend using texts, such as the name or ID of an object.

Closing a Popover

The popover is closed when the user clicks or taps outside the popover or selects an action within the popover.

Guidelines

  • Show status information as text fields in a content group. You can use semantic text colors.
  • You can define a height for the popover. If the content exceeds the height, a scroll bar is displayed.

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

Implementation

Object Page – Snapping Header

The snapping header is the uppermost element of the object page layout. It summarizes selected data and actions in a visually prioritized position to let the user quickly grasp the most relevant information.

This snapping header control is only available for the object page floorplan.

Information
The dynamic page also has a “snapping header” feature (called dynamic page header) and looks quite similar. However, this is part of the dynamic page control, and is technically not the same as the snapping header for the object page.

Usage

Use the snapping header if:

  • You are using the SAP Fiori element for the object page floorplan.
  • You are creating an object page manually based on the object page floorplan.

Do not use the snapping header if:

  • You are using any other floorplan.

Responsiveness

The snapping header is designed to provide maximum flexibility. It adapts automatically to small, medium, and large screen sizes.

The header title and subtitle never truncate. If necessary, the text wraps to the next line.

The toolbar follows the standard toolbar overflow guidelines by adding the available buttons to the overflow menu from right to left.

Object Header Content Priority

Each facet in the header content area has a priority assigned to it. Content prioritization aims to support responsive behavior. Priorities allow less important content to be omitted from rendering, depending on the screen space available. The user can always access omitted content on request.

Three priority types are available: high, medium, and low. According to the screen size, the facets are distributed as follows:

  • Size L/XL: The facets with high, medium, and low priority are displayed.
  • Size M: The facets with high and medium priority are displayed.
  • Size S: Only the facets with high priority are shown.
Snapping header – Responsiveness – Size L/XL
Snapping header – Responsiveness – Size L/XL
Snapping header – Responsiveness – Size M
Snapping header – Responsiveness – Size M
Snapping header – Responsiveness – Size S
Snapping header – Responsiveness – Size S
Snapping header content priority for sizes S, M, and L
Snapping header content priority for sizes S, M, and L

Components

The snapping header comprises two main control elements:

  • Mandatory: Title bar (sap.uxap.ObjectPageHeader)
  • Optional: Header content (sap.uxap.ObjectPageHeaderContent)

There are different states for the snapping header. You can find further information within Behavior and Interaction.

Title Bar

The title bar comprises the following elements:

  • Mandatory: Header title
    The title is always visible.
  • Optional: Header subtitle
  • Optional: Title bar image
    The image has a shape parameter (square or with a round mask) and a placeholder parameter. The placeholder is displayed if no specific image is available.
  • Toolbar
    The toolbar contains the global actions for the floorplan. The actions should be represented only with buttons, text, or an icon. They can be transparent, regular, highlighted, or semantic. All buttons go from right to left into the overflow. Buttons should be arranged according to the current use case and always in a consistent visual order (see guidelines for example). If there are no global actions, the toolbar is not shown. Note that the object page uses the sap.m.Toolbar control instead of sap.m.OverflowToolbar.
  • Child page visualization
    Each object page can have drilldown navigation. The child object page can only be reached through the parent object page. A narrow vertical stripe at the left side of the snapping header helps to differentiate the child object page from the parent object page.

The title bar can also contain the following optional indicators:

  • Favorite (property: markFavorite)
  • Flagged (property: markFlagged)
  • Locked (propertly: markLocked)
  • Selector (property: showTitleSelector)
  • Unsaved Changes (property: markChanges)

The title bar control also supports breadcrumb navigation. For more information scroll to section Line Item Navigation.

Snapping header – Structure
Snapping header – Structure

Header Content

The header content is optional and located below the title bar.

You can use the header content (sap.uxap.ObjectPageHeaderContent) to display app-specific contextual information. You build the content using smaller content containers, called facets. Each facet contains a distinct information set, as described below. If there aren’t any facets, the header content is always hidden.

The facets are arranged in line with a left float. Each facet adapts its size to the content and makes optimal use of the space without truncating the texts. If the facets do not all fit on one line, those on the right wrap to the line below.

If the snapping header collapses, the header content is hidden. If the header content is empty, you can also hide it.

Header container – Floating content
Header container – Floating content

Header Facets

There are several types of header facets, depending on the data that they display. The facets need to be handmade for stand-alone object pages.

Form Facet (Data Set)

The form facet can be used to display datasets in the snapping header. It consists of a headline and up to five label-text pairs.

  • The headline is optional
  • Contains at least one but maximum five label-text pairs
  • The labels can be invisible, but need to have a text for accessibility reasons
  • The labels can be icons, but need to have a text for accessibility reasons
  • Each text of a label-text pair can have a press event

Examples for the usage of form facets are document information such as creator and creation time, an address or contact information, and general information.

Header Facet - Form Facets
Header Facet - Form Facets

Plain Text Facet

The Plain Text Facet can be used to display a continuous text in the snapping header. It consists of a headline and a continuous text.

  • The width of the facet does not depend on its content, but can be set. The default width of the facet is 300px
  • The headline is optional
  • If the headline is broader than the facet width, the headline will wrap
  • Press events are only available inline in the continuous text. These can be links that navigate to another page or open a quickview. There can be more than one link in the continuous text with different actions.
Header Facet - Plain Text Facet with default width
Header Facet - Plain Text Facet with default width
Header Facet - Plain Text Facet with custom width
Header Facet - Plain Text Facet with custom width

Image Facet

The Image Facet can hold exactly one image. The Snapping Header can only hold one or no image facet.

  • The Image can be either square or round
  • The Image can also hold an icon
  • The Image can also hold initials consisting of two letters
  • The Image can have a press event. The default press event is the enlargement of the image.

When the Header collapses, the image facet will move to the right of the title and become smaller.

Recommended usage of the different properties:

  • Images of peoples, especially portraits, should be round. In case there is no image for a person, initials (first letters from first and last name) should be used
  • Other images should be square. In case there is no image for an object, an appropriate icon should be shown.

In all cases it should be clear, how the images will be managed and uploaded. This can either be via the edit mode of the object page or, especially when there are a lot of images via an external tool.

Header facet – Image facet specification
Header facet – Image facet specification

Key Value Facet

The key value facet holds a label in a smaller font size and a text or number in a bigger font size. It can be used to highlight important data or KPIs of the object.

If the key value facet is used with a text such as a status, it can also have an icon on the right side next to the text. This icon has to belong to the text and should only visually support but not expand it.

Header Facet – Key Value Facets with KPIs and a status
Header Facet – Key Value Facets with KPIs and a status

Micro Chart Facet

The micro chart facet consists of a headline, a subtitle, a micro chart and a footer.

The headline and the micro chart are mandatory while the subtitle and the footer are optional. To display the unit used in the micro chart, the footer should be used.

The following micro charts can be used in the micro chart facet:

  • Bullet Chart
  • Column Chart
  • Trend Chart
  • Comparison Chart
  • Delta Chart
  • Harvey Ball Chart
  • Radial Chart

The micro chart facet can have a click or tap event on the chart itself. This could for example lead to a page with a bigger chart or open a quickview.

For more information see micro charts.

Header facet – Micro Chart Facets
Header facet – Micro Chart Facets

Progress Indicator Facet

The progress indicator facet consists of a mandatory headline and a progress indicator (sap.m.progressIndicator). Further it can have two optional supplementary texts: a subtitle and a footer.

Header Facet - Progress Indicator Facet
Header Facet - Progress Indicator Facet

 Rating Indicator Facet

The Rating Indicator Facet consists of a headline, a rating indicator and one or two supplementary texts, which are depended from the use case as described below.

The rating indicator can be modified as described in the rating indicator article.

We recommend the following properties for the rating indicator used in the header facets:

  • We recommend to use 5 symbols as default.
  • We recommend to use the icon favorite as symbols.
  • We recommend to use the option to display also half stars in case of decimal values

 

The Rating Indicator Facet can be used for two different use cases which are described below.

Aggregated Rating:

When displaying an aggregated rating, which could be for example the average of several user reviews for a product, the facet can have a mandatory header, an optional subtitle, the rating indicator itself and a footer.

The subtitle should display the amount of data the aggregation is based on. For example, in the case of an average rating, the subtitle would hold the number of ratings.

The footer should hold the exact value of the aggregation in the format “2.2 out of 5”, where “2.2” indicates the exact value of the aggregation and “out of 5” indicates the maximum value of the rating.

Single Value Rating:

When displaying the rating as a single value, the facet can have a mandatory header, an optional subtitle and the rating indicator itself. Here the subtitle can be used as supplementary text and a footer should not be used.

Header Facet - Rating Indicator Facet with Aggregated Rating
Header Facet - Rating Indicator Facet with Aggregated Rating
Header Facet - Rating Indicator Facet with Singe Value Rating
Header Facet - Rating Indicator Facet with Singe Value Rating

Behavior and Interaction

The snapping header has different types of behavior that can be combined:

  • Snapping
  • Title bar only
  • Header content always shown
  • Child page visualization
  • Line item navigation
  • Edit

Per default the snapping is enabled and title bar and header content are shown (expanded).

Snapping

The snapping header is always expanded for all display sizes when the user opens the object page .

When the user scrolls down the page, the header content snaps closed (collapses), leaving only the title bar. This allows the user to see more of the object page content.

You can specify which information is shown in the title bar in the expanded and collapsed states. In the example shown opposite, the snapping header has been configured to show only the image in the title bar when the header content area is collapsed.

Snapping header – Expanded
Snapping header – Expanded
Snapping header – Collapsed
Snapping header – Collapsed

Title bar only

If there is no need for the header content, the title bar only mode can be used. This means that there is no header content shown at all, but only the title bar. This means that there is no snapping behavior, because the title bar is always shown.

Header content always shown

The snapping header can stay expanded while the user scrolls down the page if the property alwaysShowContentHeader is set to true for the object page layout (sap.uxap.ObjectPageLayout). This behavior is available only for desktops.

Child page visualization

Each object page can have drilldown navigation. The child object page can only be reached through the parent object page. A narrow vertical stripe at the left side of the snapping header helps to differentiate the child object page from the parent object page. To navigate between the child object pages of one parent object page, arrows are displayed within the header bar of the page. To easily navigate back to the object page, breadcrumbs are used. To enable the child page visualization use property isChildPage of sap.uxap.ObjectPageLayout.

Snapping Header - Child Page Visualization
Snapping Header - Child Page Visualization

Line item navigation

The snapping header for the object page can contain a breadcrumb that shows the navigation path for the current item. This feature was developed specifically for line item navigation within the object page.

The breadcrumb is located above the title in the title bar. The interaction is typical of a breadcrumb navigation pattern: all links in the breadcrumb chain point to a URI and are triggered by a press event.

If there is not enough space to show the full breadcrumb, it defaults to a dropdown control. In this case, the breadcrumb shows only the immediate parent of the current item. The   symbol indicates that further information is available in a dropdown list.

The dropdown list reveals all the links in the breadcrumb chain. The user reads the breadcrumb from bottom to top: the root object is at the bottom of the list, the immediate parent is at the top, and the current item is selected.

Snapping Header - Breadcrumbs
Snapping Header - Breadcrumbs

Edit

There are two different ways to edit the header information:

  • Global edit
  • Partial edit

Please note: the grand majority of object pages do not have editable header content. Thus in default state the object header should not be editable.

Global edit

A button in the header toolbar triggers the edit mode. For more information on global edit see also the Object Pages Article.

The visible facets can differ in create, edit and display mode. If there aren’t any facets in one mode, the header content is not displayed. Choose which information supports the user best in his current task.

 

The mental model behind this possibility assumes a number of header facets assigned to one given application. You can define which facets are shown in which mode.

Once edit mode is active, the header content is moved to a section in the content area of the object page. This section is assigned the anchor label Header. This is the first section in the document. All other sections are displayed in the order in which they had been displayed in display mode. If editable, object page title, subtitle and image appear in the header content section. They also remain visible in the header title bar. If changed they update only as a preview.

If the image is changed in edit mode, the image in the header title bar should update only as a mean of preview. The user will have to save the document to actually enable the changes.

Exemplary scenarios when switching from display to edit mode:

  • When all of the header elements are editable
    All of the header elements are displayed as editable forms in the Header section. The header content hides as no facets are displayed.
  • When only some of the header elements are editable
    All of the header elements are displayed in the Header section, but the content that is not editable is displayed as read-only to keep the layout consistent.
  • When independent header facets are present in edit mode

    All of the header elements are displayed as editable forms in the Header section. A new facet that is related to the data the user is editing is displayed in the object page header content area. This header facet is not present in display mode.

Partial edit

Partial edit is used when the object page consists of large data sets and the user wants to be able to edit only the object header. Edit mode is triggered by a button that is located on the bottom right of the snapping header.

When there are only a few elements to be edited, the Edit Header button opens a dialog. When there are more editable elements, the button triggers a subpage. This subpage contains all editable data from the header without the toolbar, the navigation, and the breadcrumbs.

Style

The snapping header is available with both flavours of the Belize theme:

  • Belize (light flavor)
  • Belize Deep (dark flavor)
Snapping header – Belize
Snapping header – Belize
Snapping header – Belize Deep
Snapping header – Belize Deep

Guidelines

Breadcrumbs
Use breadcrumb navigation only on the object page, and only where there is a hierarchical drilldown within the object (line item navigation). For other types of navigation, see the SAP Fiori navigation patterns.

Header toolbar
Do not use input fields, selects, checkboxes, search fields, or similar controls in the header toolbar. Use buttons only.

Header content area
Place only meaningful information in the header content containers. The content should help the user in the object context, or provide useful reference information.

Keep the header as clean and uncluttered as possible to allow users to take in the content at a glance. If there is too much information in the header, consider placing an overview section in the content area of the object page floorplan.

Themes

Until theme parameters are available for the snapping header, we recommend using the light flavor. This will avoid any contrast issues that might arise with the dark theme in the current implementation.

Images
When images are used in the object page header, you should consider the following needs:

  • How will the user manage the images?
  • How will the system block people without permission for image editing?
  • How will these images be reflected in other floorplans if they are part of the object?
  • If there are a large number of items, how would a company be able to manage images without having to navigate from page to page?
  • Will the company be able to manage the images?
Developer Hint
How to achieve a small header:

  • The header container is always optional. If there is no important data to be displayed, you can omit it.  In this case, only the header title bar will be shown.
  • Omit the image if it is not necessary. It is generally the tallest element in a header container.
  • Use a light theme to reduce the emphasis in the header if there is not much information on it.
  • You can always place the information from the header into a general information section.

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

Implementation

Map Container

The map container is a predefined feature set for maps. It fits most use cases and makes it easier for app developers to work with maps.

If you wish to display a geomap or an analytic map without using the map container features, the app developer can also opt to use the analytic map or geomap control.

Responsiveness

The width and height of the map container are defined by the surrounding application layout.

The map container uses the overflow toolbar control. This control is based on the sap.m.Toolbar and provides overflow when the contents do not fit in the visible area.

Note: Map container on smartphone displayed menu button instead of list panel icon because of the small screen size.

Components

Overview of map container components
Overview of map container components

The map container includes the following components:

  • A map (geomap or analytic map)
  • Transparent toolbar containing the following buttons:
    • View switch (optional), such as between geomaps and analytic maps
    • Selection menu (optional)
    • Personalization/settings (optional)
    • Full-screen mode
    • Overflow toolbar (generic)
  • A list panel stack, which can be used for a legend or other application-specific content
  • Navigation tools such as:
    • Measure
    • Scale
    • Zoom in/zoom out, including rectangular zoom
    • Home button

View Switch (Optional)

View switches are optional control. This control allows the user to switch between different map types, charts, and table layouts. You should consider using a view switch for accessibility reasons. For example, users with visual impairments might have a hard time working with subtle color differences or specific color gradients, and might prefer switching to a table view instead.

We recommend using no more than three types of alternate visualization. The segmented button control is used to display the types of visualization available in the view switch, and highlights the type of visualization that is being currently displayed.

The button control gives the user the option to switch between the geomap, analytic map and image view.
The button control gives the user the option to switch between the geomap, analytic map and image view.

Menu for Selection Modes (Optional)

The menu for selection modes enables the user to switch between the available selection modes: single, rectangular, and lasso. These buttons are optional.

Selection menu
Selection menu

Personalization (Optional)

A personalization button is provided and can be enabled/disabled by the app developer. The corresponding popover and details need to be implemented by the app developer.

The personalization/settings button can be used to show or hide a legend and labels, for example.

Personalization/settings button
Personalization/settings button

Full-Screen Mode

The map container can be viewed on full-screen mode (property: fullScreen). For desktop and tablet, the Full Screen button is always placed at the top right of the transparent toolbar.

The user can toggle between embedded and full-screen mode via the Maximize Full Screen toggle button. In full-screen mode, the map container occupies the entire width and height. The toolbar replaces the page header bar, and the Minimize icon appears.

For smartphones, the Full Screen button is disabled as the map container is used in full-screen mode by default.

Initiate full-screen button
Initiate full-screen button
Minimize full-screen button
Minimize full-screen button

Overflow (Generic)

The overflow is activated if there is not enough space on the screen for all the chart bar actions. It is generated automatically.

When the user clicks the overflow button, a popover appears. In this action sheet, all icon buttons are labelled with text.

All buttons go into the overflow from right to left.

Overflow button
Overflow button

Prioritization

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

  • Always overflow: The action will always move into the overflow.
  • Disappear: This applies to actions that are not very relevant for the user, and which can disappear if space is limited.
  • Low: This applies to actions that the user seldom needs; these actions then move first into the overflow.
  • High: These actions remain visible until all actions that are tagged ‘disappear’, ‘low’, or that are untagged, have moved into the overflow.
  • Never overflow: These actions will always visible in the toolbar.

All items have equal priority by default. If two items have the same priority, the one on the right overflows first.

Grouping

Items can overflow together, even if they are in different positions. Elements that belong to a group should not have ‘always overflow’ or ‘never overflow’ statuses as these priorities force the items to remain either in the toolbar or in the overflow area. When group elements have different statuses, the priority of the group is defined by the highest priority of its elements.

List Panel Stack (Optional)

The list panel stack is aligned to the left in the toolbar. It can be used for a legend and other application-specific content. The list panel stack can be collapsed in a way that only the icons of the different list panels will be seen. We recommend using icons that are easy to understand for each panel, as these icons will be the only visible element when the panels are collapsed. The collapsed list panels serve as quick access to the clicked panel icon.

If you are not using icons for the panels, do not allow the panels to collapse.

The default width of the list panel stack is auto. We recommend defining a precise width to avoid having the width permanently change according to the content. The list panel stack will remain visible on the map, whereas the toolbar buttons will be hidden.

As a general rule, avoid using too many panels as too much scrolling will increase the complexity of the application.

The list panel provides the same features as the standard list item:

  • Grouping
  • Select items
  • Include Icons/color markers or pictures
  • Show counter
Collapsed list panel stack (desktop)
Collapsed list panel stack (desktop)
Expanded list panel stack (desktop)
Expanded list panel stack (desktop)

Legend

We recommend to include the map legend in the list panel. All necessary features for a legend are provided through the list panel stack (see above).

If your specific use case does not allow you to include the legend in the list panel, you can also use the map legend.

Navigation Tools

Home Button

The map container provides a Home button. Clicking on the Home button leads to the initial zoom position.

Home button
Home button

Rectangular Zoom

The Rectangular Zoom button can be used to zoom to a specific position. The rectangular zoom is enabled for the compact form factor by default, and disabled for the cozy form factor. For more information on cozy and compact form factors, see content density.

Rectangular Zoom button
Rectangular Zoom button

Zoom In/ Zoom Out

The map container provides Zoom In ( ) and Zoom Out ( ) icon buttons, which are positioned on the bottom right corner of the map. When the user clicks these buttons, the chart automatically zooms in or out to the most appropriate scale.

By default, these buttons are enabled.

Zoom In/Zoom Out button
Zoom In/Zoom Out button

Behavior and Interaction

The buttons have a set priority for the overflow by default. The application developer can change this priority. High-prioritized buttons will overflow last.

On desktop and tablet devices, the list panel stack is always visible, whereas the transparent toolbar overflows. The navigation control is hidden behind the panel list stack.

On a smartphone devices, the list panel stack is minimized to a menu button on the top left. The menu icon always remains on the screen, whereas the transparent toolbar buttons overflow. Clicking on the menu button, the list panel stack opens in full-screen mode.

We generally recommend using either icon buttons or text buttons within the transparent toolbar, but not both. Icons and text should not be combined into one button. Buttons with icon and text only appear in the overflow menu. Buttons are always aligned to the right.

Guidelines

  • Think carefully about what actions you really need in the transparent map toolbar – do not overload the map toolbar with actions.
  • Think carefully about what content you really need in the panel list stack – do not overload the panel with content.
  • Think carefully about which features make sense on the map if the map is not used in full screen. For example, it wouldn’t make sense for a map to have a list panel stack if it is being featured on a card of an overview page.
  • Use tooltips for switchable content. For example, label icon buttons as “geomap” or “analytic map” in the 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

Implementation

Implementation

No links.

Object Header

Information
Do not use the object header control for the object page floorplan. For object pages, always use the snapping header control.

The object header usually represents an object instance. As such, it contains the most important information a user needs to see in order to understand what the object is about and what its status is. It is the first control on a page dedicated to a single object instance, usually the object view or flat object view.

The control can also be used as the header of other pages, such as a full screen. In that case, the object header contains the most important aggregated information of the items that are listed below.

Usage

Use the object header:

  • As the first component on a page that handles a single object instance (object view or flat object view) to enable the user identify it easily.
  • As the header of other pages, such as a full screen. In this case, the object header contains the most important aggregated information of the items that are listed below.

Do not use the object header:

  • Inside the content area as a work-around for visualizing something that is not possible with current means.

Responsiveness

The object header generally adjusts to different screen sizes. To achieve this, there is a built-in rule set that defines which content wraps or truncates when necessary, and how attributes and status texts are arranged depending on the screen size.

The object header has two flags that influence its appearance and resizing behavior: Responsive and FullScreenOptimized.
Object header – Split-screen layout (Responsive = true, FullScreenOptimized = false)
Object header – Split-screen layout (Responsive = true, FullScreenOptimized = false)

Responsive

As of SAPUI5 1.28, the app team should generally set the Responsive flag to ‘true’. In this case, the attributes are the first set of entries in the header, followed by the second set of statuses. The on-screen distribution differs from previous SAPUI5 versions. Even if there are many attributes and only a few statuses, use of the space is now optimized as the entries fill the respective columns equally.

Object header – Smartphone size (Responsive = true, FullScreenOptimized = false)
Object header – Smartphone size (Responsive = true, FullScreenOptimized = false)

Full Screen Optimized

The second attribute, FullScreenOptimized, should be activated when the header makes full use of the screen width and is not used in a split-screen layout.

Object header – Full screen optimized (responsive = true, FullScreenOptimized = true)
Object header – Full screen optimized (responsive = true, FullScreenOptimized = true)

Attribute/Status Distribution

The following table shows how the attributes are distributed automatically when the Responsive flag is set to ‘true’ on various screen sizes.

Screen Size 2 Attributes 3 Attributes 4 Attributes 5+ Attributes
Desktop (full screen) Next to the title area (1 column of 1-2 attributes) Next to the title area (1 column of 3 attributes) Underneath the title area (4 columns split by 1/1/1/1) Underneath the title area (4 columns split by 2/1/1/1)
Desktop (split screen layout) Underneath (2 columns split by 1/1 Underneath (2 columns split by 2/1) Underneath (2 columns split by 2/2) Underneath (3 columns split by 2/2/1)
Tablet (full screen – landscape) Underneath (2 columns split by 1/1) Underneath (3 columns split by 1/1/1) Underneath (3 columns split by 2/1/1) Underneath (3 columns split by 2/2/1)
Tablet (split screen layout) or Tablet (full screen – portrait) Underneath (2 columns split by 1/1) Underneath (2 columns split by 2/1) Underneath (2 columns split by 2/2) Underneath (2 columns split by 3/2)
Smartphone Underneath (1 column of 1-2 attributes) Underneath (1 column of 3 attributes) Underneath (1 column of 4 attributes) Underneath (1 column of 5+ attributes)

Prior to SAPUI5 1.28 (Responsive Set to ‘False’)

The Responsive flag is deactivated by default in apps that were built before SAPUI5 1.28. As mentioned above, this mainly impacts the attributes and status arrangement. If the Responsive flag is turned off, all attributes are left-aligned in the object header and all statuses are right-aligned, regardless of their individual number.
The object header still reacts correctly to resizing, but does not make optimal use of the space available.

For example, three attributes and one status with Responsive and FullScreenOptimized both set to ‘false’ results in two columns: the first (left) column contains three attributes, and the other column (right) has one status.  Altogether, this is three rows in height, whereas the same number of entries on a desktop full screen with the two flags set to ‘true’ results in a height of just one row (spread over four columns).

Components

Title

  • The object header has a mandatory title that serves as the key identifier of the object instance (property: title).
  • Long titles wrap once before they truncate on the second line.
  • A title can be actionable (property: titleActionable), in which case, it looks like a link and triggers an event, which usually results in a quick view.
  • An additional icon or image that identifies the object (property: icon) can be shown in front of the title. The icon or image can also be set to actionable (property: IconActionable).
  • Additionally, the title can show a title selector (which is visualized like a menu). It is mainly used to provide navigation targets, allowing the object to be opened in a different app.
Object header (Responsive=false) – Title not actionable
Object header (Responsive=false) – Title not actionable
Object header (Responsive=false) – Title actionable
Object header (Responsive=false) – Title actionable
Object header (Responsive=false) – Title selector
Object header (Responsive=false) – Title selector

Object Number

  • The object number contains the key attribute of the object instance.
  • The object number consists of text that represents the key attribute of an object, usually a number (property: number) and its unit (property: numberUnit). The object number has a semantic color (property: state). The unit inherits the semantic color of its number.
  • As usual in SAP Fiori, the semantic colors available are negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
Object header (Responsive=false) – Negative object number
Object header (Responsive=false) – Negative object number

Object Attribute

  • The object header can contain 0 to n attributes (property: objectAttribute).
  • The attributes are listed first in the list of attributes in the object header.
  • Attributes can be text (property: text) or actionable (property: actionable), in which case, they are rendered similar to links.
Object header (Responsive=false) – Attribute active
Object header (Responsive=false) – Attribute active

Object Status

  • The object header can contain a list of 0 to n object statuses (property: objectStatus).
  • The statuses are listed as the second set of attributes in the object header.
  • The status has a semantic color.
  • Statuses can be text or icons. A combination of the two is technically also possible, in which case, the icon is placed in front of the text. We generally recommend that you use text only (see guidelines below).
  • A progress indicator may also be shown as a status. If used, the progress indicator should be the last item in the list of statuses.

Object header (Responsive=true) – Favorite, three object attributes, and one object status
Object header (Responsive=true) – Favorite, three object attributes, and one object status

Flag and Favorite

  • Objects can be shown flagged and marked as favorites. The object header provides flags for both (properties: markFavorite, markFlagged).
  • To show them in the object header, you also need to activate the respective flag (property: showMarkers).
  • When they are used and shown, they appear directly behind the title.
Object header (Responsive=false) – Flag, favorite, two object attributes, and two object statuses
Object header (Responsive=false) – Flag, favorite, two object attributes, and two object statuses

Intro

  • As mentioned above, another component from the early days of SAP Fiori called the intro (property: intro) is available.
  • It is now shown directly below the title in a smaller font size.
  • The intro can call an event if it is set to actionable (property: introActionable).
  • Previously, the intro appeared above the title, and was used to indicate the origin of an object (for example, Forwarded by…, On behalf of …). It now tends to be used as a short subtitle.
Object header (Responsive=true) – Intro text used as subtitle
Object header (Responsive=true) – Intro text used as subtitle
Object header (Responsive=false) – Intro text
Object header (Responsive=false) – Intro text

Condensed

  • The object header provides a condensed flag for cases in which it is used as a page header with little information (property: condensed).
  • When turned on, the object header displays only the title, object number, and one attribute.
Object header – Condensed mode
Object header – Condensed mode

Guidelines

Settings

  • Set the object header responsiveness flag to ‘true’ (property: responsive) to make optimal use of the screen real estate.
  • If your app runs in full-screen mode (not master/details), make optimal use of the header area by setting the respective property to ‘true’ (property: FullScreenOptimized).
  • If you need to enforce the sequence and stable display of the attributes independently of the screen size, such as for an address, you might still decide to set the Responsive property to ‘false’ as an exception.

Title

  • The object header contains a mandatory title, which serves as the key identifier of the object instance (property: title). The title should be easily readable text without any IDs. If an ID is essential to the user, for example, to distinguish between identical titles, it can be put in brackets, such as Product ABC (1234567). If it is usually a long number, you can also consider adding it as a first attribute. In that case, however, you must give it a label (property: title of the Object Attribute).
  • Although the title can be truncated, keep it as short as possible and only as long as necessary.
  • If you make the title actionable and use an image or icon as well, both should be actionable and trigger the same event.
  • If you do use a title selector, it should open an action sheet that allows the user to choose from different options.

Object Number

  • The object number contains the key attribute of the object instance, which is usually a numeric attribute. In rare cases, it can also be used with text if that is the key attribute of the item. Be careful when you use text because it often leads to issues during translation if the text is too long.
  • As usual with SAP Fiori, the semantic colors available are negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
  • For very long numbers, use a formatter.
  • The object number can be left blank if there is no key attribute worth showing.

Object Attribute

  • These object attributes do not generally need a label if it is clear what they refer to. If attributes are not distinct, you can use a label (property: title).
  • To facilitate recognition of the object header, we recommend using no more than four attributes.

Object Status

  • Although it is technically possible to show icons together with text, we recommend using text only.
    • Only use icons that are clear and unambiguous. If you think your icon would need a descriptive text to be understood, use text only.
    • In the case of locked items, however, you may also add further information about who has locked the item (when available).
  • The same rule for choosing semantic colors as elsewhere in SAP Fiori applies for the statuses negative (property: error), critical (property: warning), positive (property: success), and neutral (property: none).
  • In terms of indicating status priority, the general guidance is: very high (property: error), high (property: warning), medium, low, or other (property: none).
  • You can also show a progress indicator as a status. If you use it, the progress indicator should be the last item in the list of statuses.
  • As with the attributes, statuses do not need a label if it is clear what they refer to. If statuses are not distinct, you can use a label (property: title).
  • Here, too, we recommend that you have no more than four entries in the status list (including progress indicators and flag or favorite).

Intro

  • The intro usually contains a short subtitle and should only be used when necessary.
  • Do not use the intro for standard attributes.

Master/Details

  • When used in the details area of the split screen (master/details) and the master list contains object list items, the object header should show the same information as the object list item, plus additional information if necessary.
  • Unlike the object list item, the object number uses large number formatting because the object header has more space for handling long text.

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

Implementation

Carousel

The carousel allows the user to browse through a set of items. It always displays one item at a time. From the displayed item, the user can navigate to either the next or the previous item. The interaction resembles browsing through the pages of a book.

Optionally, a paging indicator displays the user’s current position inside the set of items.

The control is best known for browsing through a set of images, as it works best when the single items are represented in a way that the user can easily distinguish. Nonetheless, the carousel is not limited to displaying images; it can contain every sap.m control.

Usage

Use the carousel if:

  • You have strong visual representations of the items you want to display.
  • You want to display the items one after the other.

Do not use the carousel if:

  • The items you want to display need to be visible at the same time.
  • The items you want to display are uniform.

Responsiveness

The size of the control’s content area is automatically adjusted to the amount of space available.

When used in non-touch mode, the user can navigate with forward and backward icons displayed on the left and right side of the control.

On touch devices, the carousel control makes use of the swipe gesture to navigate through the items. Therefore, the forward and backward icons are not displayed on touch devices.

The paging indicator (when activated) is visible on each form factor. The paging indicator wraps if not all items fit in one line.

Carousel (size S)
Carousel (size S)

Carousel (size M)
Carousel (size M)

Carousel (size L)
Carousel (size L)

Layout

The carousel control mainly consists of a content area in which the different items are displayed and cycled through.

Optionally, a paging indicator can be displayed floating either above the top or at the bottom of the content area.

On non-touch devices, icons for navigating to the next or previous item are displayed either floating above the left and right side of the content area or in the paging indicator area. This is controlled by the arrowsPlacement property.

Schematic layout of carousel
Schematic layout of carousel

Behavior and Interaction

The current item is displayed in the content area.

Navigating

When the user navigates from a displayed item to another item, the item is moved out of the content area and the next or previous item (depending on the direction of navigation) appears with a sliding transition.

On touch devices, navigation is performed with swipe gestures (swipe right or swipe left).

On non-touch devices, navigation is provided by icons.

When the item set contains only one item, the navigation is deactivated.

Navigation – Previous
Navigation – Previous
Navigation – Next (hover)
Navigation – Next (hover)

Looping

The carousel can be set to loop (property: loop). In this case, the carousel jumps back to the first item once all items have been displayed. If looping is not enabled, there is no forward navigation on the last item.

Paging

The current position inside the set of items is displayed using an optional paging indicator (properties: showPageIndicator, pageIndicatorPlacement).

Paging indicator
Paging indicator

If there are more than 8 pages, the paging indicator changes from icons to numbers.

Paging indicator
Paging indicator

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

Image (guidelines)

Implementation

Lightbox

The lightbox control allows the user to view an image in its original size. This control displays the image in a popup while dimming the rest of the screen.

Usage

Use the lightbox if:

  • The thumbnail view is not detailed enough, and it would help the user to see the image in its original size.
  • The original size of the image is bigger than the thumbnail.

Do not use the lightbox if:

  • The image you are using is smaller than or as big as the thumbnail.
  • There is another click event attached to the image control.
  • You are using an image placeholder to display the object.

Responsiveness

The lightbox container is displayed in the middle of the screen.

The image is displayed in its original size unless the original image size is bigger than the size of the screen. In this case, the image is resized proportionally in order to be fully visible and fit on the screen.

On a mobile device, flipping the device to landscape mode will flip the lightbox. The image will then be adjusted to fit the new dimensions.

Lightbox - Size S
Lightbox - Size S
Lightbox - Size M
Lightbox - Size M
Lightbox - Size L
Lightbox - Size L

Components

The lightbox contains the following components:

  • Lightbox container: This is the main container that holds all other components.
  • Image: This component is an embedded image control that displays the image file with the maximum available size. The size of the image should not exceed the original size and it should fit within the screen.
  • Image title: This component is mandatory and is used to describe the object to which the image is attached.
  • Image subtitle: This component is optional and is used to give additional information about the object.
  • Close button: This is a mandatory component and is used to close the lightbox container.
The components of the lightbox
The components of the lightbox

Behavior and Interaction

Basic Interactions

The lightbox control is attached to the press event of the image control. To trigger the lightbox, the user should click an image. Every image with an attached lightbox control is indicated with a zoom icon on the bottom right.

Lightbox - Zoom icon
Lightbox - Zoom icon

When the lightbox control is triggered, the lightbox overlays the page content and the rest of the screen is dimmed out.

If it takes more than one second to load the original image, a busy indicator is shown inside the lightbox container.

The user can close the lightbox by clicking the Close button or by clicking outside of the lightbox container.

Lightbox - Basic interactions
Lightbox - Basic interactions
Lightbox - Image loading
Lightbox - Image loading

Error Handling

An error message is displayed inside the lightbox when:

  • The original file is missing or the connection to the server is lost.
  • The image takes more than 10 seconds to load due to a server error or the size of the image.
Developer Hint
The URL of the image is mandatory. If it is not specified, the lightbox will not be triggered.
Lightbox - error message
Lightbox - error message

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

Implementation

Radial Micro Chart

The goal of the radial chart is to display one single percentage value. It is displayed with a semantically colored radial bar and a percentage value.

Different radial charts
Different radial charts

Usage

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

Responsiveness

See the Micro Chart 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

Implementation

Radial Micro Chart (SAPUI5 Explored)

Delta Micro Chart

The delta micro chart helps to visualize a delta value between two main key figures. The delta can be a positive or negative value. Configured thresholds define the semantic coloring of the delta bar. The left-aligned labels can be omitted, whereas the right-aligned labels with the values are always shown.

Different delta charts
Different delta charts

Usage

The delta micro chart can be embedded into the table, list, tile and header.

Responsiveness

See the micro chart 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

Implementation

Comparison Micro Chart

The comparison chart is a bar chart. It compares entries in a top N list. You can choose between two different layouts depending on the available space/parent container. You can use the semantic color palette as well as the chart palette.

Different comparison charts
Different comparison charts

Usage

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

Responsiveness

See the micro chart 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

Implementation

Comparison Micro Chart (SAPUI5 Explored)

Column Micro Chart

A column chart (also known as a bar chart) uses rectangular bars to compare categories. One axis of the chart shows the specific categories being compared, the other axis represents a value.

Note: The current version does not show axis or data point labels.

Only semantic colors (good, critical, bad, neutral) can be used.

Multiple column charts
Multiple column charts

Usage

The column micro chart can be embedded into the table, list, tile and header.

Responsiveness and Adaptiveness

See the micro chart 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

Implementation

Area Micro Chart

A trend chart is a line and area chart that provides the same information as a bullet chart, with one difference. While a bullet chart shows an additional forecast value, a trend chart provides information for a specific range of time.

The actual value is displayed as a solid line, the target value as a dotted line, and the thresholds as colored areas in the background.

You can show labels for the start value, the end value, the minimum value, the maximum value, and the beginning and end of the time range.

Area micro chart with horizontal forecast
Area micro chart with horizontal forecast

Usage

The area micro chart can be embedded into the table, list, tile and header.

Responsiveness

See the micro chart 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

Implementation

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 singular values as part of a whole. These values can be displayed in two different ways:

  • Percentage compared to 100%

    Use „% values“ if your goal is to see the composition in percentage of each value of the whole. By doing so, the sum of the bars will always be 100%.

%-Values (without labels)
%-Values (without labels)

  • Values compared to a maximum value

    Use „Values compared to a max value“ in list or table if your goal is to compare the sum of values to a maximum (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)
Absolute values (without labels)

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

Usage

The stacked bar micro chart can be used in the following ways.

List or Table

The micro stacked chart can be embedded in a table with all the functionalities and options mentioned above.

Chart in table: %-values (without labels)
Chart in table: %-values (without labels)
Chart in table: absolute values (without labels)
Chart in table: absolute values (without labels)


Header

The micro stacked chart can be embedded in an object page header with all the functionalities and options mentioned above.

Chart in Header: %-values (with labels)
Chart in Header: %-values (with labels)
Chart in Header: absolute values (with labels)
Chart in Header: absolute values (with labels)

Please consider using a Harvey Ball micro chart as alternative visualization to show a part to whole representation.



Tile

The micro stacked chart is not designed to be embedded into an SAP Fiori tile and is therefore not supported. Please consider to use a Harvey Ball micro chart as alternative visualization to show a part to whole representation.



Responsiveness

See the micro chart overview article.

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

Besides the displayed default %-values of the bars, an application developer can set a specific display value to enable the display of absolute values. If the intention is to show bars only, please put a a blank space here.

Color

An application developer can set any color for the chart either by using names of semantic colors ( for example, “red” for negative values or “green” for positive values) or by using names from the qualitative palette (sapUiChartPaletteQualitativeHue1…11).

Please note: A legend is currently not available for the stacked bar micro chart and since the use of multiple colors is not self-explanatory, we highly recommend using semantic colors and explanatory title related to 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

Implementation

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
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).

 

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
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

Implementation

  • Text (SAPUI5 samples)
  • Text (SAPUI5 API reference)

Footer Toolbar

The footer toolbar always appears as floating footer at the bottom of the screen. The floating footer property creates some padding between screen and toolbar, improving visibility.

The control is used for closing or finalizing actions that impact the whole page. It is only visible when actions appear, when message handling is visible, or when the draft indicator is displayed. One main advantage of the footer bar is that this bar is always visible and will not scroll away.

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

Buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons will go into the overflow last.

Usage

Use the footer toolbar:

  • If you have closing or finalizing actions on your page that apply to the whole page.

Do not use the footer toolbar:

  • If you have different containers on your page (such as charts, tables, and forms) and the action influences only certain items. In this case, place the action as close to the corresponding item(s) as possible.
  • If you have global actions (such as Edit or Delete) that are not finalizing or closing actions. In this case, use the header toolbar instead.

Responsiveness

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

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

Footer toolbar - Size S
Footer toolbar - Size S
Footer toolbar - Size M
Footer toolbar - Size M
Footer toolbar - Size L
Footer toolbar - Size L

Components

The footer toolbar can contain the following components:

  • Message indicator
  • Draft indicator
  • Finalizing/closing actions
Examples of possible components
Examples of possible components

All closing or finalizing actions are placed on the right side of the toolbar.

The footer toolbar can also include a message and draft indicator. For more information, see draft handling and messaging.

Behavior and Interaction

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

The buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons will go into the overflow last.

Styles

Button styles should be used to help the user and not for decoration.

They should be defined for actions that a user will use mostly, such as Save.

Use a positive or negative (property: type – accept/reject) or an emphasized (property: type – emphasized) styled button. Avoid using both styles on one screen.
  • Exception: Message button appears

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

Implementation

Responsive Table – Content Formatting Cheat Sheet

A table often implies a “boring” layout. It contains plain text, one value per cell, and fails to catch the user’s attention. In contrast, the responsive table is much more flexible and eye-catching. It also contains many options for formatting the table content. Due to small screen widths on mobile devices, these options are necessary in order to reduce the number of visible columns.

This cheat sheet shows you how you can transform a plain table into the cutting edge style of SAP Fiori. Take a look at the example below.

Usage

Use this cheat sheet if:

Do not use this cheat sheet if:

Guidelines

Step
01
Starting point: A “traditional” table with one line of text per cell.

Traditional table
Traditional table
Step
02
Change the alignment:

  • Left align text, IDs, phone numbers, URL, passwords, and email addresses
  • Right align numbers (except IDs and phone numbers), dates, and times
  • Center one-word status information

Change the alignment
Change the alignment
Step
03
Use the object identifier control to display key identifiers.
Use the object identifier control for key identifiers
Use the object identifier control for key identifiers
Step
04
Use the object number control (sap.m.ObjectNumber, property: emphasized) to emphasize the key attribute (usually the value of a value-unit combination).
Use the object number control to display key attributes
Use the object number control to display key attributes
Step
05
To indicate status information, use an object status control with semantic text colors. For more information on semantic colors, see colors.
Use the object status control to display status information
Use the object status control to display status information
Step
06
Remove columns by displaying the ID in brackets behind the corresponding name.

Use ID formatting and reduce the number of columns
Use ID formatting and reduce the number of columns
Step
07
To gain even more width per column, remove additional columns by combining them.
Combine columns
Combine columns

And you’re done. With just a few simple steps, you can easily bring the SAP Fiori style to a plain table.

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

Implementation

Chart Popover

A popover is used to display information or an action related to the selected data points. By default, the chart component:

  • Displays dimension members and measure values fed into the chart that relate to the data point.
  • Displays the number of selected items when in multiselection mode.
  • Does not display related actions.

The entire content of the popover can be changed or a related action can be added at the end.

Selection and Popover

The content displayed in the popover depends on the selection mode; in other words, whether the chart is in single-selection or multiselection mode.

When the user clicks or taps an item that is not selected, the popover appears displaying information about this selected item only. The item that was previously selected becomes deselected.

In Single-Selection Mode

When the user clicks or taps an item that is not selected, the popover appears displaying information about this selected item only. The item that was previously selected becomes deselected.

Popover in single-selection mode
Popover in single-selection mode

In Multiselection Mode

When the user clicks or taps an item that is not selected, the item is added to the selection. The popover appears with information about this last selected item and any other selected items. When the user clicks or taps an item that is already selected, this item is removed from the selection. If there are no more selected items, the popover disappears.

Popover in multiselection mode
Popover in multiselection mode

Structure

The following figure provides an overview of the structure:
Popover structure
Popover structure
Section Explanation Provided by default Customizable
Related information about last selected item Contains all related information about the last selected item. In single-selection mode, this is the single selected item. In multiselection mode, this is the last item added to the selection. Yes Yes. If the app developer wants different information, this section should be replaced entirely. Text only cannot be changed and another value cannot be added.
Number of selected items Displays the number of items in the selection. Only used when multiple items are selected. Yes No
Related actions Displays actions that act on all selected items. No Yes. The app developer can add its own actions. See the section below about related actions.

Default Information

By default, the chart component displays all information related to the last selected item. The first row displays dimension members. A color marker is displayed and uses the same color as the selected item. Measures are displayed below with their associated values.
Default display
Default display

With multiple dimensions, the dimension members are concatenated and displayed in the following order:

  • Firstly, the dimensions displayed in the legend.
  • Secondly, the dimension displayed in the axis. If there is more than one dimension in the axis, the dimension closest to the axis is displayed first.

The first row is wrapped if necessary.

Multiple dimensions display
Multiple dimensions display
If the selected item contains multiple measures, all measures are displayed above the category.
Multiple measures display
Multiple measures display

Number of Selected Items

If multiselection is possible, the popover displays the number of items that have been selected. If multiple items have been selected, it is not possible to display the values of all selected items. If you need to display these values, you will have to develop your own solution. For example, you can add a Compare Values or Display Values button at the bottom of the popover. This button is only displayed when multiple items have been selected.

Related Actions

You can add related actions at the end of the popover. These related actions may vary depending on the current selection. Related actions can generally be used to do the following:

  • Display more information.
  • Display another type of visualization.
  • Display another dataset.
  • Navigate to another page or app.

If an action is dedicated to showing more detailed information about the selection, use the View Details label. Actions that are specific to the entire chart or to the app should not be provided in the popover. In this case, it is better to provide them at app level, such as in the app toolbar.

Examples of popovers with one and three related actions
Examples of popovers with one and three related actions

Group of Actions

Do not display more than four actions in the popover. If more are needed, use in-place navigation.

Example of in-place navigation
Example of in-place navigation

Customization and UI Controls

The UI controls for customizing the popover are shown below:

UI controls for customization
UI controls for customization

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

Implementation

No links.

Footer Toolbar

The footer toolbar always appears as floating footer at the bottom of the screen. The floating footer property creates some padding between screen and toolbar, improving visibility.

The control is used for closing or finalizing actions that impact the whole page. It is only visible when actions appear, when message handling is visible, or when the draft indicator is displayed. One main advantage of the footer bar is that this bar is always visible and will not scroll away.

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

Buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons will go into the overflow last.

Usage

Use the footer toolbar:

  • If you have closing or finalizing actions on your page that apply to the whole page.

Do not use the footer toolbar:

  • If you have different containers on your page (such as charts, tables, and forms) and the action influences only certain items. In this case, place the action as close to the corresponding item(s) as possible.
  • If you have global actions (such as Edit or Delete) that are not finalizing or closing actions. In this case, use the header toolbar instead.

Responsiveness

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

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

Footer toolbar - Size S
Footer toolbar - Size S
Footer toolbar - Size M
Footer toolbar - Size M
Footer toolbar - Size L
Footer toolbar - Size L

Components

The footer toolbar can contain the following components:

  • Message indicator
  • Draft indicator
  • Finalizing/closing actions
Examples of possible components
Examples of possible components

All closing or finalizing actions are placed on the right side of the toolbar.

The footer toolbar can also include a message and draft indicator. For more information, see draft handling and messaging.

Behavior and Interaction

Our general guideline is to use only icon buttons or text buttons. Icon and text should not be combined into one button. Buttons are always right-aligned.

The buttons are sorted from frequently-used to seldom-used. This ensures that the most important buttons will go into the overflow last.

Styles

Button styles should be used to help the user and not for decoration.

They should be defined for actions that a user will use mostly, such as Save.

Use a positive or negative (property: type – accept/reject) or an emphasized (property: type – emphasized) styled button. Avoid using both styles on one screen.
  • Exception: Message button appears

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

Implementation

Form

Information
With version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: the data is presented as label-input field pairs, so users can enter data.
  • Mixed: some fields are editable and some are not.
Form Control in read-only mode
Form Control in read-only mode
Form Control in editable mode
Form Control in editable mode
Developer Hint
The smart form property editable really switches the smart form between edit mode and read-only mode. For example, fields become texts and vice versa.

The property editable of the form and simple form only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the whole form between editable and read-only mode, thus changing fields into text and vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M, because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L, because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL, because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend to change the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

form with a label-field-ratio 3:5:4
form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected (e.g. labelSpanL sets the label span in size L) in Forms and SimpleForms, you must change the property adjustLabelSpan from its default true to false.

Otherwise..

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for reasons of backward compatibility.

Input controls like input fields can be displayed in both – cozy and compact mode (for more information, see content density (cozy and compact). To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.
Form in size M
Form in size M

Size L

The form, simple form, and smart form in size L use a two-column layout within the responsive grid layout by default. That means that the form groups are placed next to each other to have all the information on one screen and to avoid scrolling. In these columns, the labels are positioned in the same row as the corresponding input field or value. So the form groups adopt the Z layout (reading direction in rows, not in columns).

The label-field ratio is 4:8:0 by default:

  • 4 grid columns of the responsive grid layout are used by the labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size L
Form in size L

Size XL

Like the form, the simple form, and the smart form in size L, the size XL uses also a two-column layout within the responsive grid layout by default. To have all the information on one screen and avoid scrolling, the form groups are placed next to each other.  In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

The label-field ratio for size XL is 4:8:0 (technically the value is set to -1 and inherits the value of size L, see also the development hint below) by default:

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title – instead, use the form title.

Form with only one group (form title)
Form with only one group (form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full screen – size M (3:5:4)
Form in full screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

Information
With SAPUI5 version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

With a form, you can easily layout a list of properties and input fields. A form is structured into form containers. Each form container consists of form elements. And each form element consists of a label and an input field.

The simple form control gives you the possibility to achieve the same result as with the form control, but in a much easier way. Inside a simple form, a form control is created along with its form containers and form elements:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).
  • All other controls following this label will be assigned to its row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to build UIs without the need to build a complex UI code (the term “smart” refers to the annotations that add semantics and structures to the provided data). The goals are to ensure design consistency, keep apps up to date with evolving design guidelines, and reduce the amount of front-end code for building SAP Fiori apps. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: the data is presented as label-input field pairs to allow users to enter data.
  • Mixed: some fields are editable and some are not.
Form in read-only mode
Form in read-only mode
Form in editable mode
Form in editable mode
Developer Hint
The smart form property “editable” switches the smart form between edit and read-only modes. For example, fields become texts and vice versa.

The form and simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Breakpoints

Size S reaches up to 600 px. This means that as soon as the width of the form reaches 601 px, it changes from S to M because the default value of breakpointM is 600. The value of breakpointM is the first value of the smaller size.

Form with breakpointM – Size S
Form with breakpointM – Size S
Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way: Size M reaches from 601 px to 1024 px. This means that as soon as the width of the form reaches 1025 px, it changes from M to L because the default value of breakpointL is 1024.

Form with breakpointL – Size M
Form with breakpointL – Size M
Form with breakpointL – Size L
Form with breakpointL – Size L

Also the property breakpointXL between sizes L and XL works in the same way as before: Size L reaches from 1025 px to 1440 px. This means that as soon as the width of the form reaches  1441 px, it changes from L to XL because the default value of breakpointXL is 1440.

Form with breakpointXL – Size L
Form with breakpointXL – Size L
Form with breakpointXL – Size XL
Form with breakpointXL – Size XL

In general, if the page width changes to a smaller size, the width of the form in the next smaller breakpoint is usually reached before the width of the page reaches its breakpoints in that size. For example the width of a form reaches breakpoints M to S before the width of the page reaches the breakpoints from M to S. This happens due to the padding of the container in which the form is placed.

Padding of a container
Padding of a container
Developer Hint
To set the form’s breakpoints individually and to synchronize it with the breakpoints of the page, you can use the breakpointS / breakpointM / breakpointL / breakpointXL. If you are using a simple form, set these properties directly in the simple form control.

Label-Field Ratio

For each size, you can define how many grid columns are used for labels (labelSpanXL, labelSpanL, labelSpanM, labelSpanS), fields (implicitly), and empty grid columns (emptySpanXL, emptySpanL, emptySpanM, emptySpanS).

The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the input fields. This ratio is displayed as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

We highly recommend changing the default of the label-field-ratio according to your app’s needs. For more information, see the recommended layouts in the Layout section.

form with a label-field-ratio 3:5:4
form with a label-field-ratio 3:5:4
Developer Hint
To make the properties labelSpanXL, labelSpanL, labelSpanM, and labelSpanS in the responsive grid layout work as expected in forms and simple forms, you must change the property adjustLabelSpan from its default true to false.

Otherwise:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column; it applies for both – M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column; it also applies for both M and L screen sizes.
  • The default value of the property adjustLabelSpan is set to true for backward compatibility reasons.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy and compact modes. For more information, see content density.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout within the responsive grid layout in size S by default. This means that the form groups are positioned below each other in a single column and the labels are positioned above the fields to avoid truncation of the labels.

The label-field ratio is 12:12:0 by default:

  • 12 grid columns of the responsive grid layout are used by the labels.
    (A label handles the space of a whole row.)
  • 12 grid columns of the responsive grid layout are used by the fields.
    (A field handles the space of a whole row.)
  • 0 grid columns of the responsive grid layout are used by empty columns.
    (There is no empty space on the right of the field.)
Form in size S
Form in size S

Size M

Size M of the form, simple form, and smart form also has a single-column layout within the responsive grid layout by default. However, in size M the labels are positioned in the same row as the corresponding input field or value, and form groups are positioned below each other.

The label-field ratio is 2:10:0 by default:

  • 2 grid columns of the responsive grid layout are used by the labels.
  • 10 grid columns of the responsive grid layout are used by the fields.
  • 0 columns of the responsive grid layout are used by empty columns.
Form in size M
Form in size M

Size L

The form, simple form, and smart form in size L use a two-column layout within the responsive grid layout by default. That means that the form groups are placed next to each other to have all the information on one screen and to avoid scrolling. In these columns, the labels are positioned in the same row as the corresponding input field or value. So the form groups adopt the Z layout (reading direction in rows, not in columns).

The label-field ratio is 4:8:0 by default:

  • 4 grid columns of the responsive grid layout are used by the labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size L
Form in size L

Size XL

Like the form, the simple form, and the smart form in size L, the size XL uses also a two-column layout within the responsive grid layout by default. To have all the information on one screen and avoid scrolling, the form groups are placed next to each other.  In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

The label-field ratio for size XL is 4:8:0 (technically the value is set to -1 and inherits the value of size L, see also the development hint below) by default:

  • 4 grid columns of the responsive grid layout are used by labels.
  • 8 grid columns of the responsive grid layout are used by fields.
  • 0 grid columns of the responsive grid layout are used by empty columns.
Form in size XL
Form in size XL
Developer Hint
For forms, simple forms, and smart forms, the value of the properties labelSpanXL, emptySpanXL and columnsXL are set to -1 and inherit the value of size L (to enable backward compatibility).

Layout

One Page, One Form

If a form contains only one group, do not use a group title. Instead, use the form title.

Form with only one group (using form title)
Form with only one group (using form title)

If the form is the only element on the page and if it has more than one group, you can use the group titles to capture the groups. 

One form with several groups (no form title)
One form with several groups (no form title)

If the form is one of several elements on the page, such as tables and lists, use the form title as its caption.

A form as one of several elements on a page (form title)
A form as one of several elements on a page (form title)

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Form in a split screen – size M (4:7:1)
Form in a split screen – size M (4:7:1)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form in full-screen – size M (3:5:4)
Form in full-screen – size M (3:5:4)

As explained already in the section Responsiveness (Breakpoints), Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with long labels and fields – size M (4:8:0)
Form with long labels and fields – size M (4:8:0)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with its label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with several form groups (two columns) – size M (12:12:0)
Form with several form groups (two columns) – size M (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size L (3:5:4)
Form with a single form group (one column) – size L (3:5:4)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). As explained already in the section Responsiveness (Breakpoints), Size L goes down to 1025 px. In this size, long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Therefore labels are put above fields.

Form with several form groups (two columns) – size L (12:12:0)
Form with several form groups (two columns) – size L (12:12:0)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Form with a single form group (one column) – size XL (3:5:4)
Form with a single form group (one column) – size XL (3:5:4)

The responsive grid layout has the new property singleContainerFullSize. This property enables you to insert empty columns in your form: You can for example then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty. For more information, see also the development hint below.

Form with an empty column – size XL (4:8:0)
Form with an empty column – size XL (4:8:0)

If the form is put into a full-screen app, with the property singleContainerFullSize you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Form with empty columns – size XL (12:12:0)
Form with empty columns – size XL (12:12:0)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with multiple form groups (two columns) – size XL (4:8:0)
Form with multiple form groups (two columns) – size XL (4:8:0)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form with two form groups (three columns) – size XL (12:12:0)
Form with two form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)
Form with three form groups (three columns) – size XL (12:12:0)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

Form with a lot of white space (two columns)
Form with a lot of white space (two columns)
Form with less white space (single-column layout)
Form with less white space (single-column layout)

Use of Columns

Recommended:

  • XL2-L2-M2-S1
  • XL2-L2-M1-S1
  • XL2-L1-M1-S1

Also possible:

  • XL3-L1-M1-S1
  • XL1-L1-M1-S1

Not recommended:

  • XL3-L2-M2-S1
  • XL3-L2-M2-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize.If you are using a simple form, set this property directly in the simple form control. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Order the form logically from a user’s perspective. For example, ask for a user´s name before asking them for their address.
  • Group related information by using form and group titles.
  • Try to arrange form groups (especially in size L and XL) in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • A label is not a help text. Give each field a meaningful label. Labels should be succinct, short and descriptive.
  • If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property in the API for this. Do not write the asterisk manually in the label text. just use the corresponding property and the asterisk will be inserted automatically.
  • At the end of the label, the form container automatically inserts a colon (:), which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, labels are not supported for manual bold formatting.)
  • Less is more: try to minimize the number of labels and their corresponding fields as much as possible.
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Form Field Validation

Provide form field validation which describes the validation points and the choreography associated with messaging. For more information, see form field validation.

Field validation and validation report
Field validation and validation report

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

Information
With SAPUI5 version 1.36, the smart form has been introduced as an additional control for building forms.

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using three different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

  • The layout and structure are defined by the content that is entered.
  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

The smart form control belongs to the new set of smart controls. Smart controls give developers the possibility to built UIs with annotations and without the need to build a complex UI code. Compared to the corresponding standard controls, however, the settings may be limited.

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form
Developer Hint
The smart form property “editable” switches the smart form between edit and read-only modes. For example, fields become texts and vice versa.

The form and simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). With the form and simple form, it does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, Breakpoint M, S size
Form, Breakpoint M, S size

The properties “breakpointL” between sizes L and M, and “breakpointXL” between sizes XL and L, work in the same way. The default value of breakpointL is 1024, and of breakpointXL it is 1440.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To make the properties “labelSpanXL”, “labelSpanL”, “labelSpanM”, and “labelSpanS” work as expected in the responsive grid layout (for example, to ensure that labelSpanL sets the label span in size L) you must change the property “adjustLabelSpan” to “false” in forms and simple forms. The value of the property “adjustLabelSpan” is set to “true” by default for reasons of backward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form, simple form, and smart form use a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoints for size L are set by default to 1024 px (breakpointL = 1024 ) and 1440 px (breakpointXL = 1440). This means that if the form has more than 1024 px, but no more than 1440px available, it renders the L layout. So the L layout ranges from 1025 px to 1440 px. It can be changed with the properties breakpointL and breakpointXL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Size XL

The breakpoint for size XL is set by default to 1440 px. This means that if more than 1440 px are available, the form is rendered in XL layout. It can be changed with the property breakpointXL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default (the value is set to -1 and inherits the value of size L). In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size XL
Form in size XL

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to UI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Desktop Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns). Size L goes down to 1025 px, so long labels that are put next to the fields might not fit on smaller L-sized screens (especially in split apps). Labels are therefore put above fields.

Simple form, two columns (L)
Simple form, two columns (L)
Developer Hint
Unlike all other XL-L-M-S properties, labelSpanL and labelSpanM up to UI5 version 1.34 did not follow the XL-L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set adjustLabelSpan to ‘false’.

Size XL (Desktop Wide Screens)

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (XL)
Simple form, one column (XL)

The responsive grid layout has the new property singleContainerFullSize. If you are using a simple form, set this property directly in the simple form control. Setting this property to ‘false’ enables you to insert empty columns in your form. You can then set the property columnsXL to 2, fill one column with the single form group in a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second column empty.

Simple form, one-plus-one columns (XL)
Simple form, one-plus-one columns (XL)

If the form is put into a full-screen app, you can also set columnsXL to 3, fill one column with the single form group in a label-field ratio of 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns), and leave the second and third columns empty.

Simple form, one-plus-two columns (XL)
Simple form, one-plus-two columns (XL)

If the form contains multiple form groups, you can also use a two-column layout with a label-field ratio of 4:8:0  (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (XL)
Simple form, two columns (XL)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, three columns with empty column (XL)
Simple form, three columns with empty column (XL)
Simple form, three columns (XL)
Simple form, three columns (XL)

If you use a three-column layout for XL screens, do not use a two-column layout for L and M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: XL2-L2-M2-S1, XL2-L2-M1-S1, XL2-L1-M1-S1
  • Also possible: XL3-L1-M1-S1, XL1-L1, M1, S1
  • Not recommended: XL3-L2-M2-S1, XL3-L2-M1-S1
Developer Hint
Up to SAPUI5 version 1.34, a group in a form with only this single group covered the entire width, irrespective of the value of the properties columnsM/L. Therefore, it was not possible to create an empty column next to the single group. This had to be changed. However, the default value of columnsL has always been 2. So if single groups no longer cover the entire form, all forms with a single group are automatically changed to two column forms in size L if the default value of the property columnsL has not been changed manually to 1. Therefore, a new property had to be introduced: singleContainerFullSize. Its default value is ‘true’, which reflects the old behavior. A single group covers the entire width of the form, irrespective of  the values of the properties columnsM/L/XL. If it is set to ‘false’, the form with a single group has as many columns as the properties columnsM/L/XL are set to. The new behavior with the empty columns now can be achieved.

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size XL and L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, breakpointM, size S
Form, breakpointM, size S

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

An XL breakpoint is not yet supported by forms.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To define grid columns for labels, use the “layoutData” property for the label.
The properties “labelSpanL”, “labelSpanM”, and “labelSpanS” do not all work as expected, but cannot be changed without breaking downward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)
Developer Hint
Unlike all other L-M-S properties, labelSpanL and labelSpanM up to SAPUI5 version 1.34 did not follow the L-M-S size paradigm. LabelSpanL set the label span in layouts that contain more than one column, and labelSpanM set the label span in layouts that contain only one column. This has been changed since version 1.34. Due to downward compatibility, the new parameter adjustLabelSpan was necessary. Also due to downward compatibility, its default value is ‘true’, which causes the old behavior of the labelSpan properties. To achieve the new, correct behavior of the labelSpan properties, you must set the property adjustLabelSpan to ‘false’.

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no break point to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

Always assign the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout) for your form. Although there is a specific set of form layout controls available for forms, simple forms, and smart forms, these should not be used as they are only available to enable downward compatibility.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, size M is shown when reaching a width of 601 px.

Form, breakpointM, size M
Form, breakpointM, size M

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px.

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form, breakpointM, size S
Form, breakpointM, size S

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

An XL breakpoint is not yet supported by forms.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y represents the fields, and z the empty columns.

To define grid columns for labels, use the “layoutData” property for the label.
The properties “labelSpanL”, “labelSpanM”, and “labelSpanS” do not all work as expected, but cannot be changed without breaking downward compatibility.

  • “labelSpanL” is used for labels in forms with several form groups arranged into more than one column. It applies for both M and L screen sizes.
  • “labelSpanM” is used for labels in forms arranged into one column. It applies for both M and L screen sizes.
  • “labelSpanS” is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

There is a specific set of form layout controls for forms and simple forms. You must assign one of these form layout controls to each form and simple form by using the property “layout”.

The form layout control defines how labels and fields are arranged on the screen. Always use the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout). Please do not use any other form layout control, as these are only available to enable downward compatibility. 

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, on a width of 601 px size M is shown.

Form with breakpointM – Size S
Form with breakpointM – Size S

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px .

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

To define grid columns for labels, use the layoutData property for the label.
Exception for labelSpan:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column. It applies for both M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column. It applies for both M and L screen sizes.
  • labelSpanS is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
A form as one of several elements on a page - Form title
A form as one of several elements on a page - Form title

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Form

A form is used to present data to the user and to allow users to enter data in a structured way.

The form acts as a container for other UI elements (such as labels, input fields, checkboxes, and sliders), while structuring these into a specific layout.

In SAPUI5, forms can be built using two different controls:

The simple form control gives you the same result as the form control, but in a much easier way:

The layout and structure are defined by the content that is entered.

  • Form containers and form elements are created automatically according to the content type.
  • A title (sap.ui.core.Title (API)) automatically starts a new form group (form container), and a label (sap.m.Label (API)) automatically starts a new row (form element).

Types

There are three types of forms:

  • Read-only: the data is presented only as label-value pairs.
  • Editable: users can enter data.
  • Mixed: some fields are editable and some are not.
Editable form
Editable form
Read-only form
Read-only form

The form/simple form property “editable” only changes the height of labels for vertical alignment to a field (editable = true) or text (editable = false). It does not switch the entire form from editable to read-only mode, or vice versa.

Responsiveness

There is a specific set of form layout controls for forms and simple forms. You must assign one of these form layout controls to each form and simple form by using the property “layout”.

The form layout control defines how labels and fields are arranged on the screen. Always use the responsive grid layout (sap.ui.layout.form.ResponsiveGridLayout). Please do not use any other form layout control, as these are only available to enable downward compatibility. 

By using the responsive grid layout, the form offers a responsive layout based on a 12-column grid. There are two breakpoints, which result in three supported sizes: L, M, and S. These breakpoints are not the L, M, and S breakpoints of the page. In contrast to the page’s breakpoints, which react to the screen width, the breakpoints of the responsive grid layout react to the width of the form.

Note: For downward compatibility reasons, the default form layout control for the form and simple form is not the responsive grid layout. Therefore, you need to assign the responsive grid layout manually to each form or simple form by using the layout property.

The default value of breakpointM is 600. This means that as soon as the width of the form reaches 600 px, it changes from M to S. The value of breakpointM is the first value of the smaller size.

If the value of breakpointM is 600, on a width of 601 px size M is shown.

Form with breakpointM – Size S
Form with breakpointM – Size S

If the value of breakpointM is 600, size S is shown when reaching a width of 600 px .

Due to padding of the container in which the form is placed, this width is usually reached before the page width reaches its breakpoint from M to S. This means that the form changes from M to S before the page does. To set the form’s breakpoint individually and synchronize it with the page, you can use the property breakpointM.

Form with breakpointM – Size M
Form with breakpointM – Size M

The property breakpointL between sizes L and M works in the same way. The default value of breakpointL is 1024.

For each size, you can define how many grid columns are used for labels, fields (implicitly), and empty grid columns (emptySpanL, emptySpanM, emptySpanS). The optional empty grid columns are placed after the input elements. They avoid excessive stretching of the entry fields where necessary. This ratio is displayed in this document as x:y:z, where x is the number of grids used by the labels, y stands for the fields, and z for empty columns.

To define grid columns for labels, use the layoutData property for the label.
Exception for labelSpan:

  • labelSpanL is used for labels in forms with several form groups arranged in more than one column. It applies for both M and L screen sizes.
  • labelSpanM is used for labels in forms arranged in one column. It applies for both M and L screen sizes.
  • labelSpanS is used only for screen size S, as expected.

Input controls such as input fields can be displayed in both cozy and compact mode. To horizontally align a label next to a field, the form has different CSS in cozy mode and compact mode.

Size S (Smartphones and Dialogs)

The form uses a single-column layout in size S by default (not to be confused with the underlying grid columns). The form groups are positioned below each other in a single column. The labels are positioned above the input field or value to avoid truncation.

The label-field ratio is 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Form in size S
Form in size S

Size M

The breakpoints for size M are set by default to 600 px (breakpointM = 600) and 1024 px (breakpointL = 1024). This means that if the form has more than 600 px, but no more than 1024 px available, it renders the M layout. The M layout ranges from 601 px to 1024 px. It can be changed with the properties breakpointM and breakpointL, which are properties of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

The M size form has a single-column layout by default in which the labels are positioned in the same row as the corresponding input field or value. The form groups are positioned below each other.

The label-field ratio is 2:10:0 (2 grid columns used by the labels, 10 grid columns used by the fields, and 0 grid columns used by empty columns).

We highly recommend changing this default layout according to your app’s needs. For more information, see the recommended layouts in the Layout section.

Form in size M
Form in size M

Size L

The breakpoint for size L is set by default to 1024 px. This means that if more than 1024 px are available, the form is rendered in L layout. It can be changed with the property breakpointL, which is a property of the responsive grid layout. If you are using a simple form, set these properties directly in the simple form control.

To have all the information on one screen and avoid scrolling, the form groups are placed next to each other in two columns by default. In these columns, the labels are positioned in the same row as the corresponding input field or value. The form groups adopt the Z layout.

Form in size L
Form in size L

Layout

One Page, One Form

One form with one or more groups will usually meet your needs. In this case, use group titles, not the form title. If a form contains only one group, do not use a group title.

If the form is one of several elements on the page, such as tables and lists, you may also set a form title.

One form and one group - No form title
One form and one group - No form title
One form and several groups - No form title
One form and several groups - No form title
One form and several groups - Form title and table
One form and several groups - Form title and table

One Page, Many Forms

If you want to emphasize that some groups are very distinct, use several forms on a page instead of one form with several groups. Visually this looks more separated than using a single form with several groups. Give each form a meaningful title. If necessary, you can structure each form with groups as well. In this case, also give the groups a title.

Several forms on a page (emphasized groups)
Several forms on a page (emphasized groups)
Forms with several groups
Forms with several groups

Various Layouts

The following sections give guidance on how to configure the form so that it meets the needs of different sizes. Depending on where you place the form, we highly recommend changing the default and using one of the following layouts according to your app’s needs.

Size S (Smartphones and Dialogs)

Retain the default behavior (single column layout with a label-field ratio 12:12:0).

Form in size S (12:12:0)
Form in size S (12:12:0)

Size M (Tablet) – Full Screen

If you place the form in the details part of a split screen, use a single-column layout with the label-field ratio 4:7:1 (4 grid columns used by the labels, 7 grid columns used by the fields, and 1 grid column used by empty columns).

Split view, simple form, 4:7:1 (M)
Split view, simple form, 4:7:1 (M)

If you place the form in a full-screen app, use a single-column layout with the label-field ratio 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, 3:5:4 (M)
Simple form, 3:5:4 (M)

Size M goes down to 601 px. In this size, the 3:5:4 approach may not be wide enough for longer labels and fields. So if you expect long labels or input values, use the label-field ratio 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, 4:8:0 (M)
Simple form, 4:8:0 (M)

If you place the form in a full-screen app and it contains several form groups, use a two-column layout with the label-field ratio 12:12:0 (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (M)
Simple form, two columns (M)

Size L (Wide Screens) – Full Screen

If the form contains a single form group, use a single-column layout with a label-field ratio of 3:5:4 (3 grid columns used by the labels, 5 grid columns used by the fields, and 4 grid columns used by empty columns).

Simple form, one column (L)
Simple form, one column (L)

If the form contains multiple form groups, use a two-column layout with a label-field ratio of 4:8:0 (4 grid columns used by the labels, 8 grid columns used by the fields, and 0 grid columns used by empty columns).

Simple form, two columns (L)
Simple form, two columns (L)

If the form is put into a full-screen app and it contains multiple form groups, you can also use a three-column layout with a label-field ratio of 12:12:0  (12 grid columns used by the labels, 12 grid columns used by the fields, and 0 grid columns used by empty columns).

Due to the early breakpoint from M to L (1024 px) and no breakpoint to XL for bigger sizes, L-sized screens must fit large screens as well as screens that are slightly bigger than 1024 px. So if you use a three-column layout for extra wide screens, all labels and fields must also fit on a screen that is slightly bigger than 1024 px. Truncating labels in particular may cause problems here, so they are placed above the fields.

Simple form, three columns (L)
Simple form, three columns (L)

If you use a three-column layout for size L screens, do not use a two-column layout for size M screens as it could create a lot of white space. In this case, use a single-column layout instead.

  • Recommended: L2-M2-S1, L2-M1-S1, L3,M1,S1
  • Also possible: L1, M1, S1
  • Not recommended: L3-M2-S1

Components

These are some examples of the types of UI elements that can be placed in the form container:

  • Label and text elements, including dedicated text display containers such as object number, object status, sap.ui.unified.Currency, and so on
  • Text input controls like input field and text area
  • Selection controls such as select, combo box, date picker, radio button, and checkbox
  • Icon
  • Rating indicator
  • Progress indicator
  • Switch
  • Slider
  • Link

Guidelines

  • Try to arrange form groups in size L in a way that the form:
    • Is easy to read and understand.
    • Does not contain too much white space (split groups if necessary).
  • Give each field a meaningful label. If you have combined fields that contain, for example, a postal code and the name of a city, you can provide one combined label (postal code and city) for this group.
  • The label of a required field is marked with an asterisk (*). There is a corresponding property for this in the API. Do not write the asterisk manually in the label text.
  • At the end of the label, the form container automatically inserts a colon “:”, which is triggered by the stylesheet. Do not write the colon manually in the label text.
  • Use default settings for labels. (For example, note that labels are not supported for manual bold formatting.)
  • If an input element is in an error or warning state, provide a meaningful message for the user. There is a corresponding property valueStateText in the sap.m.Input API.

Data Loss Message

Provide a data loss message if the user accidentally navigates away from the page, such as when selecting an item in the master list and then using the Back or Home button. For details about how the message is delivered and what text you can use, see message handling.

Placeholder

Provide a placeholder (or input prompt) as 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.

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.

Also do not use the placeholder as a repetition of the label.

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

Implementation

Filter Bar / Smart 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).

Information
From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to be able 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. The desktop mode (XL/L) and tablet mode (M) provide a special optimization (expanded filter bar) to make use of the desktop’s additional screen real estate.

Size S (Smartphones)

Filter bar (size S)
Filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size M (Tablet)

Filter bar
Filter bar
Filter dialog (size M)
Filter dialog (size M)

Size L/XL (Desktops)

Collapsed filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Filter dialog (size L/XL)
Filter dialog (size L/XL)
Expanded filter bar (size L/XL)
Expanded filter bar (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. 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.
Filters dialog
Filters dialog

Expanded Filter Bar (Desktop and Tablet Only)

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.
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)

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. On the right side, the user can expand or collapse the filter bar (Show Filter Bar), open the filter dialog to view all filters for the selected variant (Filters (x), where “x” stands for the number of active filters), and execute the current filter set by clicking the Go button. The collapsed filter bar is available across all devices. If required by the use case, the filter bar can be expanded by default.
Collapsed filter bar
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 expand mechanism is only available on desktop devices.
Expanded filter bar
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 then. Filters are arranged into their respective filter groups. The user can search for a specific filter by name by using the search bar at the top. Inside the filter dialog, a variant selector is available to quickly switch between variants (you can hide the variant selector if it does not fit the app’s use case). The variant name also indicates if a variant has been modified. 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.
    Note: Due to technical challenges, a Close button appears instead of the Cancel button. As an interim solution, the Close button only closes the dialog, but does not undo any changes.
  • Clear: Clears all input fields/filters (you can hide this button if it does not fit the app’s use case).
  • 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.

On desktops, the user can add filters to the expanded filter bar by selecting the relevant checkbox next to the filter (for example, frequently-edited or important filters).

Filter dialog
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Developer Hint
For development information, see data types for the smart filter bar.
Filter/input controls
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.

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.
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03

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. Furthermore, the variant indicates its modified state with the variant selector. Note: Adding a filter to the variant (as shown) does not automatically add the new filter to the personalized expanded filter bar.
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant

Personalize 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.
Note: The expanded filter bar is only available on desktops.
  • Filter Bar - Personalize Expanded Filter Bar 01
  • Filter Bar - Personalize Expanded Filter Bar 02
  • Filter Bar - Personalize Expanded Filter Bar 03
  • Filter Bar - Personalize Expanded Filter Bar1
  • Filter Bar - Personalize Expanded Filter Bar2
  • Filter Bar - Personalize Expanded Filter Bar3

Guidelines

Default Variant Filters

Only important and frequently used filters should be selected for the app-defined initial filter subset hosted inside the expanded filter bar. Which filter should be added to the expanded filter bar generally depends on the use case and the user’s personal preference.
Default variant
Default variant

Table Filtering and Table Searching

Because the filters of the filter bar and the filter option of the table can contain confusing or even contradictory entries, you must deactivate the filter option of the table.
Do
Table without filtering option
Table without filtering option
Don't
Table with filtering option
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 collapsed
Initial state expanded
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 is located next to the variant management. If the filter bar is collapsed, the basic search field is the only input that is still visible. The basic search field is the only one that cannot be excluded from the filter bar via the filter dialog.
Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.
Basic search field – Filter bar expanded
Basic search field – Filter bar expanded
Basic search field – Filter bar collapsed
Basic search field – Filter bar collapsed

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 essential in manual update mode. If a search field is used, it is only triggered by the Go button, and not instantly.

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 manual update mode
Filter bar in live 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

Implementation

Filter Bar / Smart 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).

Information
From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to be able 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. The desktop mode (XL/L) and tablet mode (M) provide a special optimization (expanded filter bar) to make use of the desktop’s additional screen real estate.

Size S (Smartphones)

Filter bar (size S)
Filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size M (Tablet)

Filter bar
Filter bar
Filter dialog (size M)
Filter dialog (size M)

Size L/XL (Desktops)

Collapsed filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Filter dialog (size L/XL)
Filter dialog (size L/XL)
Expanded filter bar (size L/XL)
Expanded filter bar (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. 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.
Filters dialog
Filters dialog

Expanded Filter Bar (Desktop and Tablet Only)

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.
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)

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. On the right side, the user can expand or collapse the filter bar (Show Filter Bar), open the filter dialog to view all filters for the selected variant (Filters (x), where “x” stands for the number of active filters), and execute the current filter set by clicking the Go button. The collapsed filter bar is available across all devices. If required by the use case, the filter bar can be expanded by default.
Collapsed filter bar
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 expand mechanism is only available on desktop devices.
Expanded filter bar
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 then. Filters are arranged into their respective filter groups. The user can search for a specific filter by name by using the search bar at the top. Inside the filter dialog, a variant selector is available to quickly switch between variants (you can hide the variant selector if it does not fit the app’s use case). The variant name also indicates if a variant has been modified. 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.
    Note: Due to technical challenges, a Close button appears instead of the Cancel button. As an interim solution, the Close button only closes the dialog, but does not undo any changes.
  • Clear: Clears all input fields/filters (you can hide this button if it does not fit the app’s use case).
  • 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.

On desktops, the user can add filters to the expanded filter bar by selecting the relevant checkbox next to the filter (for example, frequently-edited or important filters).

Filter dialog
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Developer Hint
For development information, see data types for the smart filter bar.
Filter/input controls
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.

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.
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03

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. Furthermore, the variant indicates its modified state with the variant selector. Note: Adding a filter to the variant (as shown) does not automatically add the new filter to the personalized expanded filter bar.
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant

Personalize 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.
Note: The expanded filter bar is only available on desktops.
  • Filter Bar - Personalize Expanded Filter Bar 01
  • Filter Bar - Personalize Expanded Filter Bar 02
  • Filter Bar - Personalize Expanded Filter Bar 03
  • Filter Bar - Personalize Expanded Filter Bar1
  • Filter Bar - Personalize Expanded Filter Bar2
  • Filter Bar - Personalize Expanded Filter Bar3

Guidelines

Default Variant Filters

Only important and frequently used filters should be selected for the app-defined initial filter subset hosted inside the expanded filter bar. Which filter should be added to the expanded filter bar generally depends on the use case and the user’s personal preference.
Default variant
Default variant

Table Filtering and Table Searching

Because the filters of the filter bar and the filter option of the table can contain confusing or even contradictory entries, you must deactivate the filter option of the table.
Do
Table without filtering option
Table without filtering option
Don't
Table with filtering option
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 collapsed
Initial state expanded
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 is located next to the variant management. If the filter bar is collapsed, the basic search field is the only input that is still visible. The basic search field is the only one that cannot be excluded from the filter bar via the filter dialog.
Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.
Basic search field – Filter bar expanded
Basic search field – Filter bar expanded
Basic search field – Filter bar collapsed
Basic search field – Filter bar collapsed

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 essential in manual update mode. If a search field is used, it is only triggered by the Go button, and not instantly.

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 manual update mode
Filter bar in live 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

Implementation

Filter Bar / Smart 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).

Information
From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

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)
Expanded filter bar (size S)
Collapsed filter bar (size S)
Collapsed filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size M (Tablet)

Expanded filter bar (size M)
Expanded filter bar (size M)
Collapsed filter bar (size M)
Collapsed filter bar (size M)
Filter dialog (size M)
Filter dialog (size M)

Size L/XL (Desktops)

Expanded filter bar (size L/XL)
Expanded filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Filter dialog (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 L)
Filter dialog (size S)
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 one row of filters
Filter Bar (Size L) with more than one row of filters
Filter Bar (Size L) with more than one row of filters
Filter bar (size S) with vertical 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
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
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
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Developer Hint
For development information, see data types for the smart filter bar.
Filter/input controls
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.

Additionally recommended input fields:

Behavior and Interaction

The filter bar contains the following actions:

Select 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.

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.

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.

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
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 data sets. In this case, consider making certain default filters mandatory to help the user avoid loading very large datasets unnecessarily.

Filter without default value
Filter without default value
Filter with available Values
Filter with available Values
Filter with a default value
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
Table without filtering option
Don't
Table with filtering option
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 collapsed
Initial state expanded
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
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.

Information
On mobile devices, only the Go button and manual mode are available.
Filter bar in manual update mode
Filter bar in manual update mode
Filter bar in live 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

Implementation

Filter Bar / Smart 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).

Information
From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to be able 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. The desktop mode (XL/L) and tablet mode (M) provide a special optimization (expanded filter bar) to make use of the desktop’s additional screen real estate.

Size S (Smartphones)

Filter bar (size S)
Filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size M (Tablet)

Filter bar (size M)
Filter bar (size M)
Filter dialog (size M)
Filter dialog (size M)

Size L/XL (Desktops)

Collapsed filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Filter dialog (size L/XL)
Filter dialog (size L/XL)
Expanded filter bar (size L/XL)
Expanded filter bar (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. 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.
Filters dialog
Filters dialog

Expanded Filter Bar (Desktop and Tablet Only)

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.
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)

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. On the right side, the user can expand or collapse the filter bar (Show Filter Bar), open the filter dialog to view all filters for the selected variant (Filters (x), where “x” stands for the number of active filters), and execute the current filter set by clicking the Go button. The collapsed filter bar is available across all devices. If required by the use case, the filter bar can be expanded by default.
Collapsed filter bar
Collapsed filter bar

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 expand mechanism is only available on desktop devices.
Expanded filter bar
Expanded filter bar

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 then. Filters are arranged into their respective filter groups. The user can search for a specific filter by name by using the search bar at the top. Inside the filter dialog, a variant selector is available to quickly switch between variants (you can hide the variant selector if it does not fit the app’s use case). The variant name also indicates if a variant has been modified. 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.
    Note: Due to technical challenges, a Close button appears instead of the Cancel button. As an interim solution, the Close button only closes the dialog, but does not undo any changes.
  • Clear: Clears all input fields/filters (you can hide this button if it does not fit the app’s use case).
  • 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.

On desktops, the user can add filters to the expanded filter bar by selecting the relevant checkbox next to the filter (for example, frequently-edited or important filters).

Filter dialog
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Filter/input controls
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.

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.
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03

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. Furthermore, the variant indicates its modified state with the variant selector. Note: Adding a filter to the variant (as shown) does not automatically add the new filter to the personalized expanded filter bar.
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant

Personalize 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.
Note: The expanded filter bar is only available on desktops.
  • Filter Bar - Personalize Expanded Filter Bar 01
  • Filter Bar - Personalize Expanded Filter Bar 02
  • Filter Bar - Personalize Expanded Filter Bar 03
  • Filter Bar - Personalize Expanded Filter Bar1
  • Filter Bar - Personalize Expanded Filter Bar2
  • Filter Bar - Personalize Expanded Filter Bar3

Guidelines

Default Variant Filters

Only important and frequently used filters should be selected for the app-defined initial filter subset hosted inside the expanded filter bar. Which filter should be added to the expanded filter bar generally depends on the use case and the user’s personal preference.
Default variant
Default variant

Table Filtering and Table Searching

Because the filters of the filter bar and the filter option of the table can contain confusing or even contradictory entries, you must deactivate the filter option of the table.
Do
Table without filtering option
Table without filtering option
Don't
Table with filtering option
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 collapsed
Initial state expanded
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 is located next to the variant management. If the filter bar is collapsed, the basic search field is the only input that is still visible. The basic search field is the only one that cannot be excluded from the filter bar via the filter dialog.
Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.
Basic search field – Filter bar expanded
Basic search field – Filter bar expanded
Basic search field – Filter bar collapsed
Basic search field – Filter bar collapsed

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 essential in manual update mode. If a search field is used, it is only triggered by the Go button, and not instantly.

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 manual update mode
Filter bar in live 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

Implementation

Filter Bar / Smart 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).

Information
From a UX point of view, the filter bar and the smart filter bar work in the same way even though they are generated differently. The filter bar is configured by app developers, while the smart filter bar is generated from data services and provides a variety of automatic functions. This article contains information about both filter bars.

Responsiveness

Because tables appear in many apps, from simple to complex ones, the filter bar needs to be able 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. The desktop mode (XL/L) and tablet mode (M) provide a special optimization (expanded filter bar) to make use of the desktop’s additional screen real estate.

Size S (Smartphones)

Filter bar (size S)
Filter bar (size S)
Filter dialog (size S)
Filter dialog (size S)

Size M (Tablet)

Filter bar
Filter bar
Filter dialog (size M)
Filter dialog (size M)

Size L/XL (Desktops)

Collapsed filter bar (size L/XL)
Collapsed filter bar (size L/XL)
Filter dialog (size L/XL)
Filter dialog (size L/XL)
Expanded filter bar (size L/XL)
Expanded filter bar (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. 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.
Filters dialog
Filters dialog

Expanded Filter Bar (Desktop and Tablet Only)

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.
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)
Expanded filter bar (desktop only)

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. On the right side, the user can expand or collapse the filter bar (Show Filter Bar), open the filter dialog to view all filters for the selected variant (Filters (x), where “x” stands for the number of active filters), and execute the current filter set by clicking the Go button. The collapsed filter bar is available across all devices. If required by the use case, the filter bar can be expanded by default.
Collapsed filter bar
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 expand mechanism is only available on desktop devices.
Expanded filter bar
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 then. Filters are arranged into their respective filter groups. The user can search for a specific filter by name by using the search bar at the top. Inside the filter dialog, a variant selector is available to quickly switch between variants (you can hide the variant selector if it does not fit the app’s use case). The variant name also indicates if a variant has been modified. 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.
    Note: Due to technical challenges, a Close button appears instead of the Cancel button. As an interim solution, the Close button only closes the dialog, but does not undo any changes.
  • Clear: Clears all input fields/filters (you can hide this button if it does not fit the app’s use case).
  • 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.

On desktops, the user can add filters to the expanded filter bar by selecting the relevant checkbox next to the filter (for example, frequently-edited or important filters).

Filter dialog
Filter dialog

Variant Selector

The variant selector is used to select the current variant, and also provides access to variant management.
Variant selector
Variant selector

Filter/Input Controls

Developer Hint
For development information, see data types for the smart filter bar.
Filter/input controls
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.

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.
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03
  • Filter Bar - Slider 01
  • Filter Bar - Slider 02
  • Filter Bar - Slider 03

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. Furthermore, the variant indicates its modified state with the variant selector. Note: Adding a filter to the variant (as shown) does not automatically add the new filter to the personalized expanded filter bar.
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant
  • Filter Bar - Add Filter to Variant

Personalize 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.
Note: The expanded filter bar is only available on desktops.
  • Filter Bar - Personalize Expanded Filter Bar 01
  • Filter Bar - Personalize Expanded Filter Bar 02
  • Filter Bar - Personalize Expanded Filter Bar 03
  • Filter Bar - Personalize Expanded Filter Bar1
  • Filter Bar - Personalize Expanded Filter Bar2
  • Filter Bar - Personalize Expanded Filter Bar3

Guidelines

Default Variant Filters

Only important and frequently used filters should be selected for the app-defined initial filter subset hosted inside the expanded filter bar. Which filter should be added to the expanded filter bar generally depends on the use case and the user’s personal preference.
Default variant
Default variant

Table Filtering and Table Searching

Because the filters of the filter bar and the filter option of the table can contain confusing or even contradictory entries, you must deactivate the filter option of the table.
Do
Table without filtering option
Table without filtering option
Don't
Table with filtering option
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 collapsed
Initial state expanded
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 is located next to the variant management. If the filter bar is collapsed, the basic search field is the only input that is still visible. The basic search field is the only one that cannot be excluded from the filter bar via the filter dialog.
Note: If you need to provide a search field, use the basic search field. The search field within the table must be deactivated.
Basic search field – Filter bar expanded
Basic search field – Filter bar expanded
Basic search field – Filter bar collapsed
Basic search field – Filter bar collapsed

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 essential in manual update mode. If a search field is used, it is only triggered by the Go button, and not instantly.

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 manual update mode
Filter bar in live 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

Implementation